Runtime · Contributing

Agent plugin

Install Bun rules, skills, hooks and the bun MCP server into Claude Code, Codex, Gemini CLI, OpenCode and other coding agents.

View as Markdown Edit on GitHub

bun agent-plugin installs a Bun plugin into Claude Code, Codex, Gemini CLI, OpenCode, Antigravity (agy) and other local agent harnesses. Rules, skills and command rewriting come from one source; each agent gets its own configuration format and event protocol. The plugin provides:

the runtime's MCP server, bun mcp, over stdio;
hooks that run bun, bunx and bun uv instead of node, npm, npx, yarn, pnpm, pip and python, and bun bd test instead of bun test inside a Bun checkout;
skills for building, testing and navigating Bun, generated from the repository.

Codex receives the MCP server, the skills and AGENTS.md, but no hooks, so its shell commands are not rewritten.

Every agent found

bun agent-plugin install

Some agents

bun agent-plugin install codex gemini opencode local

From a checkout

bun scripts/aphrody/agent-plugin.ts install

The bun executable embeds a copy of the plugin. A plugin generated from a checkout can differ from that copy; bun agent-plugin doctor shows which one is installed. Installation does not change the agent's selected model, credentials or sessions.

What gets installed

Everything lands in ~/.bun/agent-plugin ($BUN_INSTALL/agent-plugin). The agents' own files are only merged into, and bun agent-plugin uninstall takes back exactly what was added:

Agent	Where	How it is registered
Claude Code	`~/.bun/agent-plugin/claude`	`extraKnownMarketplaces.aphrody-bun` and `enabledPlugins["bun@aphrody-bun"]` in `~/.claude/settings.json`, then `claude plugin install` when the CLI is on `PATH`
Codex	`~/.bun/agent-plugin/codex`	a delimited block in `~/.codex/config.toml` (`[marketplaces.aphrody-bun]`, `[plugins."bun@aphrody-bun"]`) and in `~/.codex/AGENTS.md`
Antigravity	`~/.gemini/config/plugins/bun`	a plugin directory: `plugin.json`, `mcp_config.json`, `hooks.json`, `rules/`, `skills/`
Gemini CLI	`~/.bun/agent-plugin/gemini`	native extension linked through `gemini extensions link`, `GEMINI.md`, `BeforeTool`/`AfterTool` hooks with millisecond timeouts
OpenCode	`~/.bun/agent-plugin/opencode`	merge Bun MCP/instructions into `opencode.json`, native JS plugin and skills in the OpenCode config directory
Local harness	`~/.bun/agent-plugin/local`	portable `AGENTS.md`, skills and MCP configuration; no assumed hook protocol or model-server configuration

Other plugins, marketplaces and settings are left as they are.

Every agent gets the bun MCP server (bun mcp). Claude Code also gets bun lsp as its language server (bun lsp --stdio, one server for every language it routes). The list of tools in the plugin's instructions and the extensions given to Claude Code are read from the sources (src/mcp/tools, src/agent_tools/tools.json, src/lsp/language.rs), so a tool or a language added there shows up at the next generation.

Command	Does
`bun agent-plugin install [agent]...`	install for the agents named, or every agent found
`bun agent-plugin install --update`	reinstall only when the installed copy differs, for the agents installed before
`bun agent-plugin install --dry-run`	print what would be written
`bun agent-plugin uninstall [agent]...`	remove it
`bun agent-plugin doctor [--json]`	tell whether the `bun` on `PATH` is the Aphrody runtime and which plugin is installed

agent is one of claude, codex, gemini, opencode, local and agy. --home <dir> installs into another home directory.

Hooks

The hooks are TypeScript files run by bun (bun --no-install --no-env-file hooks/<hook>.ts <agent>); each takes a few milliseconds.

Hook	Claude Code	Antigravity	Does
Session start	`SessionStart`	`PreInvocation`	checks that `bun` is the Aphrody runtime, otherwise says how to install it; in a Bun checkout, recalls `bun bd` and `bun bd test`; reinstalls the plugin when `bun` changed version
Before a command	`PreToolUse` (`Bash`)	`PreToolUse` (`run_command`)	rewrites the command, see below
Before a search	`PreToolUse` (`Grep`, `Glob`, and `rg`, `grep`, `find` in `Bash`; Claude Code only)		once per session, names the `bun mcp` tools to prefer (`graph_`, `lsp_`, `vfs_*` when the server has them)
After a command	`PostToolUse` (`Bash`)	`PostToolUse` (`run_command`)	when `node`, `npm` or `python` is not found, names the Aphrody runtime's equivalent

Command	Becomes
`npm i`, `npm install`, `npm ci`	`bun i`, `bun install`, `bun install --frozen-lockfile`
`npm install -D x`	`bun install --dev x`
`yarn add -D x`, `pnpm add -D x`	`bun add --dev x`
`npm run x`, `yarn x`, `pnpm x`	`bun run x`
`npx x`, `pnpm dlx x`, `yarn dlx x`	`bunx x`
`tsc`, `tsgo`, `bunx @typescript/native-preview`	`bun check`
`oxlint`, `eslint`, `bunx oxlint`	`bun lint`
`oxfmt`, `prettier`, `bunx oxfmt`	`bun fmt`
`n2b`, `bunx @aphrody/bun-plugin-n2b`	`bun n2b`
`bun check`, `bun lint`, `bun fmt`, `bun n2b` in a Bun checkout	`bun bd check`, `bun bd lint`, `bun bd fmt`, `bun bd n2b`
`node file.js`	`bun file.js`
`pip install x`, `python -m pip install x`	`bun uv pip install x`
`python file.py`, `uv ...`, `uvx ...`	`bun uv run python file.py`, `bun uv ...`, `bun uv tool run ...`
`bun test` inside a Bun checkout	`bun bd test`

The Python rewrites only happen when the bun that runs the hook is the Aphrody runtime, which carries uv. A rewritten command runs without confirmation only when the agent already runs without asking (Claude Code bypassPermissions); otherwise Claude Code and Antigravity ask for it. Gemini CLI and OpenCode get the same rewriting through their own hook and plugin formats.

A command ending with # keep-node (or # keep-npm, # keep-tool) is left as written; BUN_AGENT_PLUGIN_REWRITE=0 turns the rewriting off, and BUN_AGENT_PLUGIN_AUTO_ALLOW=1 runs rewritten commands without asking.

Generating

The plugins are generated, never written by hand. The generator is packages/bun-agent-plugin; scripts/aphrody/agent-plugin.ts runs it from a checkout:

bun scripts/aphrody/agent-plugin.ts generate          # packages/bun-agent-plugin/dist
bun scripts/aphrody/agent-plugin.ts generate --check  # fails when dist is stale
bun scripts/aphrody/agent-plugin.ts install           # generate and install

Its skill inputs are the repository skills in .claude/skills (hand-written, or generated from src/agent_tools/skills.json by src/codegen/generate-agent-tools.ts) and the slash commands in .claude/commands. Codex, Gemini CLI, OpenCode and Antigravity get the same skills through their generated adapters. AGENTS.md is preferred for repository guidance, with CLAUDE.md compatibility. Tool catalogs, type declarations and documentation are extracted from the checkout.

The adapter contracts describe the files each agent receives. A local model uses the adapter of the harness that runs it; an inference endpoint alone cannot load skills or run MCP tools.

The build packs the result into the executable (codegen/agent-plugin.bin), which bun agent-plugin extracts.

Agent rules

Use the Aphrody runtime (aphrody-labs/bun) for everything JavaScript, TypeScript and Python: bun instead of node, bun install/bun add/bun remove/bun run instead of npm, yarn and pnpm, bunx instead of npx for unrelated packages, bun uv instead of pip, python and uv.
Type checking, lint, formatting and migration must use native bun check, bun lint, bun fmt and bun n2b directly. Never delegate these four commands to subprocess backends, standalone Oxc tools, tsgo/tsc or external n2b. In a Bun checkout, run them as bun bd check, bun bd lint, bun bd fmt and bun bd n2b; correct native failures instead of using an external fallback. Package scripts may expose these native commands but must not wrap or replace them; bunx is reserved for unrelated packages.
Check which bun runs with bun agent-plugin doctor --json. Stable releases such as 1.4.4+<commit> are identified by process.release.sourceUrl under https://github.com/aphrody-labs/bun/releases/download/, with a matching release version and native Bun.revision commit. Older -aphrody.N releases are also recognized. The plugin's content hash identifies the plugin, not the runtime. If the runtime is not recognized, install it (curl -fsSL https://bun.aphrody.app/install | bash, or powershell -c "irm bun.aphrody.app/install.ps1|iex" on Windows) or upgrade it (bun upgrade).
The bun MCP server (bun mcp) exposes the tools of the Aphrody runtime to the agent; prefer them over ad hoc scripts when they cover the task.
In a checkout of the Bun repository, build with bun bd and test with bun bd test <file>: plain bun test runs the installed bun, not your changes. Read AGENTS.md and the repository's applicable guidance first; CLAUDE.md remains a compatible source, not a restriction to Claude.
For a task on Bun itself, load the matching skill of this plugin (bun-build, bun-tests, bun-crates, bun-runtime, bun-docs) and the reference it lists.