agentbundler

README

Agent Bundler

One source → target-specific coding-agent layouts

Claude Code · Codex · Pi · Copilot · Grok Build · Cursor · Antigravity CLI

Define coding-agent assets once. Build the target-specific trees each agent expects.

Why this exists

SKILL.md is useful common ground, but it does not define a shared metadata format, plugin/package layout, or a common way to ship agents, hooks, and scripts. Each coding agent adds its own conventions. The same instructions also do not work equally well across models: wording that helps an OpenAI model may need a different version for an Anthropic model, and vice versa.

Maintaining copied skills and plugin files for every target is tedious. Copies drift. Small target or model differences become manual release work.

Agent Bundler keeps one source of truth, then lets you customize the parts that actually need to differ: frontmatter, Markdown sections, support files, and short target-wide preambles. It renders the result into the directory layout expected by Claude Code, Codex, Pi, GitHub Copilot, Grok Build, Cursor, and Antigravity CLI.

canonical source + manifest
          │
          ▼
   import → customize → render
          │
          ├── Claude Code   .claude-plugin/ + hooks/ + skills/ + agents/
          ├── Codex         .codex-plugin/ + hooks/ + skills/
          ├── Pi            package.json + hook runtime + declared TS extensions
          ├── Copilot CLI   plugin.json + hooks.json + skills/ + agents/
          ├── Grok Build    Claude-compatible plugin + Grok hook roots
          ├── Cursor        .cursor-plugin/ + hooks/ + skills/ + agents/
          └── Antigravity   plugin.json + skills/ + agents/ + explicit native resources

Current scope

Package profiles produce skills, agents, portable resources, command hooks, payload files, and deterministic catalogs in each vendor's native layout. Claude, Codex, Copilot CLI, Cursor, Grok, and Antigravity CLI use separate plugin roots. Antigravity requires package profile and separate mode, emits no catalog, supports only agents with name and description, and rejects portable hooks. Explicit Antigravity-native rules, MCP configuration, hooks, and scripts can be copied as opaque native resources. Pi can merge several logical packages into one explicit aggregate package with its typed hook runtime and explicitly declared native TypeScript extensions. Project profiles remain available for their narrower target layouts.

Hook portability is semantic, not name-based. An unsupported event, matcher, decision, timeout, async mode, or failure policy fails with an exact diagnostic; Agent Bundler never silently weakens a security hook or drops an asset.

Agent Bundler is a compiler, not an agent runtime, installer, marketplace, or publisher. It creates target-ready files; your project or release workflow decides where to install or publish them. Run repository-owned vendor smoke tests before publishing; see Targets and CLI.

Idempotence

Idempotence is a required product quality, separate from deterministic output. With unchanged source bytes, manifest, selectors, and compiler version, a successful build must leave a current output tree untouched: no replacement, mtime change, or filesystem watcher churn. check must remain write-free, and package must preserve an existing archive when its deterministic bytes match. Real drift may still trigger the complete atomic replacement needed to remove stale output safely.

The current writer and archive implementation produce identical bytes but still replace unchanged filesystem objects. This is a known product gap, not the intended steady-state contract. Until content-aware no-op writes land, run check first and invoke build only when it reports drift. See Idempotence quality contract.

Install

Homebrew is the default install:

brew install alexei-led/tap/agentbundler

Or install with Go 1.26+:

go install github.com/alexei-led/agentbundler/cmd/agbun@latest

Start with an existing bundle

Discover the installed CLI, then build from a directory containing agentbundle.json:

agbun --version
agbun --help
agbun check
agbun build

Use agbun help build, agbun help check, and agbun help targets for the full command, safety, and target-ID reference.

build replaces the configured output directory. Use a dedicated generated directory, not a working project root. check is read-only; add --native to run only declared safe validators for Claude, Grok, and Antigravity after drift passes. Opt-in root vendor discovery can route repository installs into the generated target trees without symlinks; see repository-root compatibility. For a complete first bundle, see the quick start. For a tested Antigravity CLI plugin, see the Conductor-shaped example. For a multi-package hook example that builds all seven targets, see testdata/cc-thingz-hooks.

What can be customized

A target overlay can:

• merge or remove JSON frontmatter keys, including target-defined metadata such as tools;
• replace the whole Markdown body;
• replace the body under an exact heading path;
• add, replace, or delete support files;
• prepend a short target-wide policy through composition.

See customization for the exact sidecar format and examples.

Documentation

• Documentation index
• Quick start
• Agent skill

License

MIT

Documentation

Overview

Package agentbundler is the target-neutral Agent Bundler compiler product.

The executable entry point is cmd/agbun. Internal packages own source import, composition, target rendering, and generated-output effects.