Plugins
bro is a host — definePlugin, external loading, custom components.
bro is a plugin system on top of beads and gh. Every built-in command
is a plugin in one registry; external plugins load from config and get
the same contract — command, skill, config section, plan schema.
There are three distinct seams: CLI extensions add commands, connectors
bind external systems behind facades, and agent plugins install bro
into clients. The portable Agent Plugin is one root plugin.json plus
skills/; client-specific manifests and hooks package it for each client.
See agent plugins and the connector marketplace.
The separate “Claude Code on other agents” plugin lets Claude Code act as
a CLI client over configured agents such as OpenCode and Devin.
Client adapters
bro plugins also installs bro into agent clients — the native-plugin
clients ship an adapter module the CLI writes to the client's own plugin
directory:
| Command | What it does |
|---|---|
bro plugins list [--json] | Client × scope install matrix — installed, stale, present, absent |
bro plugins install <client> [--global|--local] [--dry-run] | Write the adapter module (a current file is a no-op; a differing one is updated) |
bro plugins uninstall <client> [--global|--local] [--dry-run] [--force] | Remove it |
Clients: opencode (a plugin directory — global
$XDG_CONFIG_HOME/opencode/plugins/bro/, local <repo>/.opencode/plugins/bro/
— holding the server entrypoint index.ts, the TUI half tui.tsx and the
RPC contract rpc.ts), kilo (module plus a file:/// entry in
kilo.json's plugin array on global installs), pi
(<agentDir>/extensions/bro.ts), omp
(<agentDir>/extensions/bro.ts, or <repo>/.omp/extensions/). Every
adapter carries a bro-adapter sentinel comment so detection survives a
rename.
Marketplace clients — Devin, Claude Code, Codex, Cursor — install from
the repo's plugin manifests instead; see
Getting started.
The omp client has a second, richer form: plugins/omp/bro is a
full omp plugin package — the adapter plus bro's skills, a pre-tool
guard hook, and WATCHDOG.md (the advisor's review priorities).
Install it with omp plugin install ./plugins/omp/bro. Its mode
bridges hand omp's native Plan, Goal, Vibe, Prewalk and Advisor the
durable state they lack — claims, specs, the judge, the review-debt
ledger — without reimplementing any of them. See
specs/bro-omp-plugin.md.
The contract
A plugin is a plain object — or typed via the side-effect-free
@broject/bro/plugin entry point:
// bro-memory.ts
import { definePlugin } from '@broject/bro/plugin';
export default definePlugin({
name: 'memory', // → `bro memory <args>`
summary: 'remember what matters', // shows in `bro plugins` + help
skill: 'memory', // skills/memory/SKILL.md
argvPrefix: ['mem'], // aliases
configKey: 'memory', // owns the `memory` config section
configSchema: raw => ({
dir: typeof raw?.dir === 'string' ? raw.dir : '.agents/memory',
}),
planSchema: validateMemoryPlan, // validates `kind = "memory"` plans
runPlan: runMemoryPlan, // executes them via `bro plan run`
run: argv => {
/* ... */
},
});Required: name, summary, run. Everything else is optional and
type-checked at load — wrong field types warn and skip the plugin.
@broject/bro/plugin also exports defineConfig, makePrinter, and
the BroPlugin / BroConfig / ConfigSection / PlanSchema types —
it never runs the CLI on import.
Loading external plugins
// bro.config.ts
export default {
plugins: ['./bro-memory.ts', '@acme/bro-standup'],
};- Relative paths resolve from the repo root and cannot escape it
- Default export must be a
BroPlugin(or an array) - Names colliding with built-ins are rejected; so are
configKeys that shadow an owned section - Invalid plugins warn and are skipped — they never crash the CLI
- TypeScript files load natively (Node ≥ 22.18, erasable syntax only —
enums and parameter properties need a build step, not
import())
Bring your own memory
Everyone's memory layer is different — that's the point of the split. A memory plugin is a plugin that owns a config section and a command:
// bro-memory.ts — a repo-local plugin
export default {
name: 'memory',
summary: 'project memory, my way',
configKey: 'memory',
configSchema: raw => ({ dir: raw?.dir ?? '.memory' }),
run: async argv => {
// write/read whatever store you want — sqlite, files, a service
},
};Artifacts that shouldn't touch the review surface go on the data ref —
bro work sync carries them. Stores, commands, config, plans: if your
component fits the contract, bro hosts it.
Guardrails
- Built-in command names and config sections are protected from external collisions
bro pluginslists the live registry — name, skill, config, summary- External plugins can't be
hiddenfrom the help output