For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/guide/start/index.md.
Skip to main content
agent-bundle
  • English

      • Introduction

      Agent Bundle is a meta-framework for building plugins for agent hosts. Write your tools, Skills, hooks, and views once. The framework discovers conventional source files, builds the executable entries, and emits the manifests required by your selected hosts.

      Start with the quick start: create a project, add a tool, see its rendered result in Workbench, and test it. You do not need to write an MCP server or learn the compiler's internal architecture first. The compiler and Workbench require Node.js 22.19 or later.

      The problem it solves

      A host is the application loading the plugin, such as Claude Code, Codex, Cursor, or experimental Amp. An MCP server exposes tools, resources, and prompts through the Model Context Protocol. An MCP App is a browser view associated with an MCP resource/tool. These are different parts of the system, not three names for your application.

      Without the framework, a composite plugin can accumulate separate tool registries, native hook wrappers, CLI handlers, browser message plumbing, and installation scripts. Agent Bundle owns those integration boundaries so application code can concentrate on what the plugin does.

      The useful analogy to a convention-based app framework is a file declares a route:

      src/mcp/status/tools/hello.tsx
                 ↓
       hello tool on the status server
                 ↓
  generated MCP entry · Workbench · tests

      Add a colocated CLI projection to expose that same operation as a command. Add an App when it needs an interactive browser view. Neither requires a second implementation of the operation.

      What the config owns

      A conventional project needs a small agent-bundle.config.ts:

      import { 
      const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactory
      defineConfig       } from 'agent-bundle/config';      

export default 
      function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactory
      defineConfig      ({      
  
      AgentBundleConfig.plugin: AgentBundlePluginConfig
      plugin      : { 
      AgentBundlePluginConfig.name: string
      name      : 'my-plugin', 
      AgentBundlePluginConfig.description?: string | undefined
      description      : 'Project tools for an agent.' },      
  
      AgentBundleConfig.targets?: string[] | undefined
      targets      : ['claude', 'codex', 'cursor'],      
});

      The plugin name is its host-facing slug; the npm package name may differ. The release version comes from package.json. Target selection does not require repeating the source tree in config. Custom MCP servers, remote endpoints, prebuilt payloads, and package entries remain supported when the conventions do not fit; they are not required setup for your first tool.

      targets selects projections: amp, claude, codex, cursor, or portable. Omitted, it selects portable alone. A selected host does not necessarily support every component or live development feature. Consult host capabilities before adding a host-specific surface.

      The authoring model

      ConceptWhat you write
      RoutesFiles under conventional roots such as src/mcp/<server>/tools/. The path supplies identity.
      ConfigurationProject identity, selected hosts, policy, and explicit exceptions.
      RenderingRendered routes return Agent.* elements describing agent-facing content and structured results. Browser Apps use browser UI code.
      Context, when neededawait agent() inside a request gives access to framework-provided context and providers. Unavailable host information is not fabricated.

      A static Skills plugin does not need a React runtime or an MCP server. A plain hook can use the public hook contract without JSX. Providers, state, and browser Apps are optional features, not boilerplate to copy into every project.

      The framework owns discovery, host translation, execution plumbing, devtools, and packaging. Your plugin still owns its domain services, authorization rules, storage model, and workflows. It does not need to turn its scheduler, database, or login flow into a framework subsystem.

      Evidence, not vibes

      Use the scaffold's check command for its complete deterministic suite. A route test proves application behavior; a packed-process test additionally checks the installed executable; a native-host test checks the host integration. These are separate claims. See testing when adding coverage beyond the starter.

      Where to go next

      • Quick start: one tool from source file to visible result and test.
      • Project structure: a composite plugin's authored files and the distinct source, generated, package, and writable-state roots.
      • Shipping a bundle: build, validate, pack the generated npm root, and install explicitly.

      Installation explains the framework preview channel. Authoring and compiler architecture are the detailed references, not prerequisites for the first working plugin.