@aaplugin/kit

Rolldown-based AI Plugin framework, public lifecycle SDK, and CLI. Platform and Extension implementations are independently installed peer packages.

Requires Node.js ^20.19.0 || ^22.13.0 || >=23.5.0.

pnpm add -D @aaplugin/kit \
  @aaplugin/platform-claude-code \
  @aaplugin/platform-codex

// aaplugin.config.ts
import { defineConfig } from '@aaplugin/kit';
import claudeCode from '@aaplugin/platform-claude-code';
import codex from '@aaplugin/platform-codex';

export default defineConfig({
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Reusable AI workflows.',
  platforms: [claudeCode(), codex()],
});

src/
├── commands/*.md
├── skills/*/SKILL.md
└── agents/*.md
public/
aaplugin.config.ts

platforms is required and there is no runtime default. init selects Claude Code and Codex only as a scaffolding default, writing their dependencies and imports explicitly. Select all six during scaffolding with:

pnpm exec aaplugin init my-plugin --yes \
  --platform claude-code codex cursor antigravity opencode pi

Or install and configure the independent packages directly:

import { defineConfig } from '@aaplugin/kit';
import antigravity from '@aaplugin/platform-antigravity';
import claudeCode from '@aaplugin/platform-claude-code';
import codex from '@aaplugin/platform-codex';
import cursor from '@aaplugin/platform-cursor';
import openCode from '@aaplugin/platform-opencode';
import pi from '@aaplugin/platform-pi';

export default defineConfig({
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Reusable AI workflows.',
  platforms: [claudeCode(), codex(), cursor(), antigravity(), openCode(), pi()],
  build: { strict: false },
});

Claude Code, Codex, Cursor, and Antigravity produce Plugin Packages. OpenCode produces a workspace overlay; Pi produces an npm Package. The compatibility report records native, transformed, degraded, and unsupported behavior before any managed output is committed.

The main package does not re-export official Platforms or Extensions and has no platforms/* subpath. Official and third-party integrations use the same definePlatform(), defineExtension(), Session, and Contributor contracts from @aaplugin/kit/sdk, so the framework needs no registry or source change to accept another implementation.

Claude Code can be configured as an explicit Platform. Omitting marketplace builds only the installable Plugin; marketplace: {} additionally creates a self-contained single-Plugin Marketplace from the top-level metadata.

Claude Code 可以作为显式 Platform 配置。省略 marketplace 时只构建可安装 Plugin；配置 marketplace: {} 时，会从顶层元数据推导并额外生成一个自包含的单 Plugin Marketplace。

import { defineConfig } from '@aaplugin/kit';
import claudeCode from '@aaplugin/platform-claude-code';

export default defineConfig({
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Reusable AI workflows.',
  author: { name: 'wh1teAlter' },
  platforms: [
    claudeCode({
      marketplace: {
        owner: { name: 'wh1teAlter' },
        category: 'Developer Tools',
        tags: ['workflow'],
      },
    }),
  ],
});

The Claude Code output uses .claude-plugin/plugin.json, commands/, skills/, and agents/. Hooks and MCP remain independent Extensions: the Platform only exposes validated hooks and mcpServers manifest extension points and never imports those Extension packages.

Claude Code 产物使用 .claude-plugin/plugin.json、commands/、skills/ 与 agents/。Hooks 和 MCP 仍是独立 Extension：Platform 只提供经过校验的 hooks 与 mcpServers 清单扩展点，不依赖对应 Extension 包。

pnpm exec aaplugin validate
pnpm exec aaplugin inspect
pnpm exec aaplugin build

Hooks and MCP are optional official Extensions（Hooks 与 MCP 通过可选的官方 Extension 启用）. Their Platform Contributors are included in the Extension packages, while each Platform remains independent of them:

pnpm add -D @aaplugin/extension-hooks @aaplugin/extension-mcp

Node Runtime is built into Core: direct TypeScript/JavaScript files under src/runtime/ are compiled once through the Core-owned Rolldown Compiler and delivered only to Platforms that declare a stable Plugin-local Node 20 ESM capability. It does not require another package or factory.

See the repository documentation for the complete authoring schema, compatibility rules, and security model.

License

MIT