Agent plugin - Aphrody Bun

Bun OS agent plugin for Claude Code, Codex, Gemini CLI, OpenCode and local-model harnesses, with native adapters, MCP and shared skills

bun agent-plugin integrates Bun OS with Claude Code, Codex, Gemini CLI, OpenCode and local-model harnesses. Rules, skills and command rewriting have one source; each harness gets its native configuration and event protocol. Antigravity (agy) remains a separate adapter.

Codex receives MCP, skills and AGENTS.md. Its Bun plugin ships no lifecycle hooks and performs no automatic shell-command rewriting.

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.

Every agent found

bun agent-plugin install

Some agents

bun agent-plugin install codex gemini opencode local

From a checkout

bun x bun-agent-plugin install

The build embeds a plugin snapshot in bun. A checkout-generated plugin can differ from the installed executable; verify both identities with doctor. Installation does not change the selected model, credentials, sessions or local model weights.

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 [claude\|codex\|agy]...`	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 [claude\|codex\|agy]...`	remove it
`bun agent-plugin doctor`	tell whether the `bun` on `PATH` is the Aphrody runtime and which plugin is installed

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 and Codex	Antigravity	Does
Session start	`SessionStart`	`PreInvocation`	checks the Aphrody runtime's native release URL and matching version/commit (or its legacy `-aphrody.N` revision), 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, Codex approval_policy = "never"); otherwise Claude Code and Antigravity ask for it, and Codex refuses the original with the rewritten one to run instead.

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 inputs include package-owned skills (packages/bun-agent-plugin/skills), neutral repository skills (.agents/skills, skills) and Claude-compatible source paths as a fallback (.claude/skills, .claude/commands). The first skill of a name wins. AGENTS.md is preferred for repository guidance, with CLAUDE.md compatibility. Runtime tool catalogs, declarations, documentation and memory fiches are extracted from the checkout; adapters are generated rather than maintained separately.

See adapter contracts for source schemas and real qualification limits. A local model uses the selected harness's adapter; an inference endpoint alone cannot load skills or execute MCP tools. No Claude JSON hooks are registered with OpenCode or Gemini.

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, qualify them with 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 revisions remain recognized. The plugin's content hash identifies the plugin, not the runtime; this provenance check does not verify an archive checksum. If the runtime is not recognized, install it (curl -fsSL https://aphrody.app/install | bash, or powershell -c "irm 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.