agent-bundle - Agent plugin compiler for Claude Code, Codex, Cursor, and experimental Amp

agent-bundle

One typed config, every agent host

Describe skills, hooks, MCP servers, and scripts once. Compile installable output for Claude Code, Codex, Cursor, and experimental Amp.

Introduction Quick start

🧩

One typed configuration

A single agent-bundle.config.ts holds identity, targets, and policy. The src/ conventions fill in everything it leaves silent, and config always wins when both describe the same thing.

📚

Skills

One directory per Skill with its SKILL.md and resources, discovered without a declaration and validated against the pinned Agent Skills specification.

🪝

Lifecycle hooks

Seven events from sessionStart to workspaceOpen, written once in TypeScript and compiled into the wrapper each host actually spawns.

🔌

MCP servers and MCP Apps

Hand-written stdio servers, or generated servers where each tool, resource, and prompt is one module. Browser MCP Apps compile to self-contained HTML.

📜

Scripts, assets, and package entries

Plain or rendered scripts, byte-for-byte assets, and a CLI bin or library entry emitted from the same project, one build, both outputs.

🖥️

Local Workbench

agent-bundle dev serves a loopback application tree and route workspace with rendered results, invocation traces, diagnostics, and advanced protocol and artifact tools.

🔬

Evidence-driven testing

Route, protocol, CLI, packed, and host-install proof levels turn "it builds" into recorded evidence, and a pass at one level is never reported as a receipt for another.

📊

Evaluations

Eval suites with pass, fail, and inconclusive semantics, run against the real emitted artifact rather than a mock of it.

📦

One root, every host

The artifact root is the unit you install, every selected host's manifest sits in its own dotfolder over shared Skills, hooks, and MCP entries, beside a generated INSTALL.md and agent-bundle.manifest.json, the artifact index that install, doctor, validation, MCP, hooks, and evals read.

What you write, and what you get

The input is one config file and a conventional src/ tree. The output is one composite plugin root: every selected host's manifest in its own dotfolder over shared component directories, generated wrappers, installation instructions written with the bundle's real names, and the agent-bundle.manifest.json the whole artifact is validated against. Every host installs that same directory.

You write

agent-bundle.config.ts

import { defineConfig } from 'agent-bundle/config';

export default defineConfig({
  plugin: {
    name: 'release-tools',
    description: 'Release-readiness checks.',
  },
  hooks: {
    sessionStart: {
      handler: './src/hooks/session-start.ts',
    },
  },
  targets: ['claude', 'codex', 'portable'],
});

src/

src/
├── skills/release-review/
│   ├── SKILL.md
│   └── references/policy.md
├── hooks/session-start.ts
├── mcp/status.ts
└── scripts/check-service.ts

Skills, the MCP server, and the script are picked up by convention. Only the hook needs a declaration, because a handler has to be bound to an event.

The compiler emits

artifact/

artifact/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .codex-plugin/
│   ├── plugin.json
│   ├── hooks.json
│   └── mcp.json
├── .agents/plugins/marketplace.json
├── .mcp.json
├── plugin.json
├── mcp.json
├── hooks/
│   ├── hooks.json
│   ├── session-start-….claude.mjs
│   ├── session-start-….codex.mjs
│   └── hooks-flight.mjs
├── mcp/
│   ├── mcp-status-….mjs
│   └── mcp-status-…-flight.mjs
├── scripts/check-service.mjs
├── skills/release-review/
│   ├── SKILL.md
│   └── references/policy.md
├── INSTALL.md                       # one section per selected host
├── install.mjs                      # installer for portable and Cursor
└── agent-bundle.manifest.json       # artifact index: identity, projections, executables

Every selected host reads this one directory as its plugin root: Claude Code finds .claude-plugin/, hooks/hooks.json, and .mcp.json; Codex finds .codex-plugin/ and the marketplace under .agents/; Agent Plugins clients find plugin.json and mcp.json. Skills, compiled MCP entries, and scripts are emitted once, never copied per host.

The Agent Plugins open standard has no hook surface. The hook above declares no targets, so it inherits only the selected targets that support hooks, claude and codex, and is compiled once per host it reaches, which is why two wrappers appear. portable is skipped without a diagnostic; naming it explicitly, targets: ['portable'], is AB4204 at build time instead.

Generated wrapper names carry a short digest of the declaration they were compiled from, not of their contents. agent-bundle.manifest.json records every emitted file with its SHA-256, so later validation compares real bytes rather than checking that a path exists.

From source to installed plugin

Describe

Write agent-bundle.config.ts and put Skills, hooks, MCP routes, and scripts under src/. agent-bundle inspect shows the normalized model, so you can confirm which files were picked up by convention and which were claimed by config.

Develop

agent-bundle dev rebuilds on every change and serves the developer Workbench on loopback: select any plugin surface in one Application tree, run executable leaves, inspect rendered results, and follow invocation traces and diagnostics.

Prove

Test against the artifact with proof levels that stay distinct, from route-unit tests up to a bundle installed through the real host CLI, and run evaluations whose results are pass, fail, or inconclusive.

Ship

agent-bundle build validates the project and writes one composite plugin root. Validation checks the artifact against its manifest, and installation points each host's own install path at that root.

One source, every host

targets selects which host projections the one root carries; omit it and the root carries portable alone. Experimental Amp reads its nested directory plugin; the other rows read the composite root.

Target	What it adds to the root	Installed with
`amp`	`.amp/plugins/<name>/index.js`, explicitly registered bundled Skills, PluginAPI event callbacks, and skill-scoped MCP. Experimental: contract-verified, runtime-unverified.	Copy the generated directory into the project/system root, or `agent-bundle install amp --from artifact`. Live activation needs an Amp account and is not proven in CI.
`claude`	`.claude-plugin/plugin.json` and a local `marketplace.json`, plus `hooks/hooks.json` and `.mcp.json`.	`claude plugin marketplace add` and `claude plugin install`, or `agent-bundle install claude --from artifact`.
`codex`	`.codex-plugin/plugin.json` with its `hooks.json` and `mcp.json`, plus `.agents/plugins/marketplace.json`.	`codex plugin marketplace add` and `codex plugin add`, or `agent-bundle install codex --from artifact`.
`cursor`	`.cursor-plugin/plugin.json` with its `hooks.json` and `mcp.json`.	The generated `install.mjs`, or `agent-bundle install cursor --from artifact`.
`portable`	The Agent Plugins open standard, `plugin.json` and `mcp.json` over Skills and MCP servers, read natively by Cursor. The hosts reference records the other clients that were checked against it, compatible, partial, and incompatible, with the surfaces each one does and does not load.	The generated `install.mjs`.

Hosts differ in what they can load, so the compiler says so at build time: a surface you select for a target that cannot express it is a reported diagnostic, never a quiet omission. The one deliberate exception is a hook with no targets of its own, which inherits only the hosts that support hooks, as the tree above shows, rather than failing. Two selected hosts that would write the same path with different bytes cannot share one root, and the build says so with AB4103. Every diagnostic has a stable AB code documented in the diagnostics reference.

Start here

Installation: requirements and the create-agent-bundle scaffolder.
Quick start: a project from config to installed plugin.
Examples: runnable products, from a Skills starter, hook and script traces, and an interactive MCP App to a complete media-management plugin, plus two advanced references.
Type API: the generated reference for every public agent-bundle export.

One typed configuration

Skills

Lifecycle hooks

MCP servers and MCP Apps

Scripts, assets, and package entries

Local Workbench

Evidence-driven testing

Evaluations

One root, every host

#What you write, and what you get

#You write

#The compiler emits

#From source to installed plugin

#Describe

#Develop

#Prove

#Ship

#One source, every host

#Start here