docs

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:

CommandWhat 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 plugins lists the live registry — name, skill, config, summary
  • External plugins can't be hidden from the help output

On this page