agent-bundle compiles an agent plugin — skills, hooks, MCP servers, and scripts, described by one typed config — into one installable plugin root that Claude Code, Codex, Cursor, and portable Agent Plugins clients load. You write the plugin once; the compiler emits each selected host's manifests and wrappers into that root.
Documentation: scriptedalchemy.github.io/agent-bundle (English and 简体中文; guide, reference, generated type API, host capability matrices).
Requires Node.js 22.19 or later.
Nothing is published to npm yet (the agent-bundle name on npm currently belongs to an unrelated project). Until the first release, install the preview tarballs CI publishes for every commit and pull request:
npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha-or-pr>Use a PR number or the SHA of a commit whose package-preview run succeeded (every green main commit has one). See Preview packages for pinning and details.
The fastest start is the scaffolder — it prompts for a name, a template
(minimal, mcp-server, or cli-tool), and the host targets, then emits a
project that already passes its own check:
npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-pr> my-plugin(npm create agent-bundle once npm releases exist. See the
create-agent-bundle README for
templates and flags.)
Or describe the plugin by hand in agent-bundle.config.ts at the project root:
import { defineConfig } from 'agent-bundle/config';
export default defineConfig({
plugin: { name: 'my-plugin', description: 'What it does.' }, // version comes from package.json
targets: ['claude', 'codex', 'cursor'],
skills: ['src/skills/*'],
hooks: { sessionStart: { handler: './src/session-start.ts' } },
mcp: { servers: { tools: { entry: './src/mcp.ts' } } },
});Then build, or work interactively:
npx agent-bundle build --root . # write the plugin root to artifact/
npx agent-bundle dev --root . # local workbench with live rebuildsagent-bundle build writes one composite plugin root (artifact/ by default; --output or output.distPath relocates it), and targets selects which host projections it carries: the .claude-plugin/, .codex-plugin/, and .cursor-plugin/ manifests and the portable plugin.json sit at the root over shared skills/, hooks/, mcp/, and scripts/ directories, emitted once. Every selected host installs from that same directory, and the generated INSTALL.md explains how. Omitting targets emits only the portable projection.
The portable target is the Agent Plugins open standard (specification 1.0.0) adapter — the default projection, and the layout Cursor loads natively (Claude Code consumes it only through CLI translation). Every other client that reads this artifact is recorded with its tier, install command, and dated evidence in the clients section of that same capability table, rendered as the hosts reference. It emits the closed root plugin.json (canonical $schema, name, version, description, plus author, homepage, repository, license, keywords, and reverse-domain extensions authored under the portable config key), skills/<name>/SKILL.md, and mcp.json with stdio and Streamable HTTP servers whose args, env values, and cwd use the standard's ${PLUGIN_ROOT}/${PLUGIN_DATA} placeholders. Rules, commands, hooks, marketplaces, and client extension directories are honestly unavailable there because the v1 standard packages only skills and MCP servers. Both documents are validated against the vendored, hash-pinned 1.0.0 schemas and the normative text at plan time (portable.mcp.*.standard), after every ordinary build and validate --artifact (AB6011/AB6012 plus the Agent Plugins byte lane AB6035–AB6037), under validate --artifact --host-validation (same lane with the AB6038 provenance note), and by agent-bundle doctor for installed Cursor local plugins that declare the standard's $schema (AB7320); see Diagnostics. Pins live in packages/agent-bundle/src/adapters/schemas/portable/PROVENANCE.json; the capability table packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json carries a dated row for every standard feature.
Claude Code language servers are declared under claude.lspServers; the claude projection emits the record as plugin-root .lsp.json. Agent Bundle expands path tokens only in command, args, env, and workspaceFolder, and it does not include the language-server binary — install that separately so the declared command is available on PATH. Codex, Cursor, and the portable format do not currently receive this host-scoped configuration.
Claude Code plugin defaults are declared under claude.settings and emitted as plugin-root settings.json, which Claude Code applies when the plugin is enabled. The pinned contract supports only agent and subagentStatusLine; Agent Bundle rejects any other key rather than shipping a default Claude Code would silently ignore, and it expands no path tokens here because settings.json is absent from the host's placeholder-substitution table. Because the plugin agents/ component is still deferred, declaring agent also raises a warning: the referenced agent has to reach the plugin root some other way, such as a prebuilt payload.
Cursor Plugin manifest metadata is declared under cursor.* and emitted verbatim into .cursor-plugin/plugin.json by the cursor projection: author (name, optional email), homepage, repository, license, keywords, plus the schema-admitted publisher, category, tags, and minClientVersions (for example { cursor: '3.13.0' }). Every field is validated against the pinned cursor/plugins manifest schema before emission — author.url, non-HTTP URLs, empty strings, and loose semver are rejected with cursor.manifest.* errors, and an invalid block emits no partial metadata. The Cursor Plugin documents never mix Agent Plugin (plugin.json, ${PLUGIN_ROOT}) paths or tokens into the Cursor Plugin format; the portable projection owns that format, even when both share one root. The full documented-surface contract matrix (every Cursor hook event, cloud availability, hook options, marketplace and team-distribution surfaces, canvases, agents) lives as dated supported / unavailable rows in packages/agent-bundle/src/adapters/capabilities/cursor-2026-08-28.json.
The same config also owns the npm package build — no second bundler config, bin shims, or hand-rolled stdio lifecycles. bin and lib entries (or the conventions src/cli.ts, src/index.ts, and src/mcp/<server-id>.ts) emit executable dist/bin/<name>.js bundles and a library output alongside the plugin root; an MCP entry that default-exports a server factory runs under a framework-owned stdio lifecycle; tools.rsbuild / tools.rspack is the one bundler escape hatch. Entry conventions is the full contract, and Framework mode is the whole authoring model on one screen: structure in config and conventions (src/skills/<name>/SKILL.md ships with no declaration at all), JSX only where something is rendered.
build— validate the project and write the plugin root (plus thebin/libpackage build when declared)validate— check project source, or a built artifact with--artifact <dir>inspect— show the normalized configuration and each selected host's projection plan;--bundlerdumps the lowered Rspack config of every compiled output (post-tools-hatch merge, as Rslib/Rsbuild hand it to the compiler)dev— serve the local development workbench and rebuild thedist/package build when its inputs change;--install-host <claude|codex|cursor>installs a development variant whose stabledev proxyMCP command hot-swaps epochs behind the host's open connection and re-syncs hooks and Skills on every adopted rebuild (see Framework mode › Live development into hosts)mcp list/mcp invoke/mcp run— list, invoke, or run an artifact's MCP servers locallyhooks list/hooks simulate— inspect and simulate generated hookseval— run eval suites against a built artifact
When the claude projection is selected, validating the built root also runs the installed
Claude Code developer toolchain in addition to the pinned schemas. Use
agent-bundle validate --artifact artifact --strict in CI; Claude's --strict findings remain
warnings locally unless Agent Bundle strict mode is requested. If claude is absent, validation
reports an explicit informational skip. For the install-free development loop, run
claude --plugin-dir artifact plugin list --json after building.
The package README is the full reference: configuration semantics, the workbench, the optional Agent API, evals, and limitations.
| Example | What it shows | Run |
|---|---|---|
| Skills Starter | author a release-review skill with deterministic evidence | pnpm example:skills |
| Hooks and Scripts | simulate a hook and inspect script traces | pnpm example:hooks |
| MCP App | an interactive MCP App with a deterministic eval | pnpm example:mcp-app |
| Audiobook Curator | a real media-management plugin for Claude or Codex | pnpm example:audiobook |
| Host Test | probe what Claude, Codex, and Cursor send to hooks and MCP calls | pnpm example:host-test |
Run these from the repository root. pnpm examples:check validates and builds every example noninteractively.
pnpm check runs the local delivery gate (build, unit and integration tests, lint, typecheck); pnpm check:release adds the packaging gates. pnpm check:local-ci mirrors the full hosted CI gate — the three-Node verify matrix plus the examples, release, and micro-eval jobs — in parallel local worktrees, and is the merge gate for the local-merge workflow described in docs/local-ci.md. Versioning goes through Changesets. Native Claude/Codex host smokes are opt-in and intentionally skipped in CI. The Workbench architecture and the optional RSC runtime are documented in docs/architecture/rsc-runtime-workbench.md.
Pre-release. The final npm package name is not yet chosen; pkg.pr.new previews are the release channel until then.
Apache License 2.0. See LICENSE and NOTICE. Third-party material in this repository (the Workbench MCP App renderer derived from the MIT-licensed MCP Inspector) is covered by its own notices in packages/workbench/THIRD_PARTY_NOTICES.