docs

Getting started

Install bro and wire it into a repo in under a minute.

ICP & JTBD

ICP: maintainers and small teams with existing agents, a task store, and PR/CI.
JTBD: deterministic lifecycle closure — task → agent → PR → gate → debt.
Wedge: start with bro act status (review gate) and bro debt status (debt ledger). Sweep merged threads with bro debt collect. No fleet, no model gateway required. Orchestration is optional and progressive.

Requirements

  • Node ≥ 22.18 — bro runs TypeScript natively (unflagged type stripping), no build step
  • gh, authenticated — review data comes from the GitHub API and bro setup requires it. On GitLab repos the review facade uses an authenticated glab, but gh stays a setup prerequisite
  • bd (beads) — the default store. Opt out with "stores": ["jsonl"] if you must

Install

npx -y @broject/bro --help     # zero install
npm i -g @broject/bro          # or keep bro around

npm latest is 0.3.0 — the grouped bro <group> <member> spellings dispatch (bro review debt status), and the flat names (bro debt status) remain available as aliases. Commands introduced in 0.3.0 are marked 0.3.0 where the docs cite them.

Wire a repo

bro setup              # checks gh + bd, writes bro.config.local.json
bro setup --beads      # also: bd init --stealth + debt-pipeline formula
bro setup --skills     # also: thin skill wrappers for your agent

bro setup writes bro.config.local.json — the gitignored machine-local layer, excluded via .git/info/exclude — and never touches the committed bro.config.{ts,json} the repo shares as policy. When a bro.config.local.ts already exists it takes precedence and setup leaves it for you to edit directly — no JSON is written. Layers merge local > project > global; the global file is $XDG_CONFIG_HOME/bro/config.{ts,json} (default ~/.config/bro/) — see Configuration. Committed bro.config.* policy already applies on a fresh checkout, before setup — defaults fill only what no layer supplies.

End-to-end scenario (no fleet/model gateway required)

# 1) Claim work from your task store
npx @broject/bro next
BEAD="<bead-id>"  # replace <bead-id> with the ID from the claimed work order

# 2) Implement and open a PR for the claimed work
git add -A
git commit -m "$BEAD: <summary>"
git push -u origin HEAD
gh pr create --fill  # open a PR for the current branch; the review gate inspects it

# 3) Drive the PR through the review gate
npx @broject/bro act status        # verdict: threads/ci/reviewers/sast/mergeable
npx @broject/bro act threads       # work unresolved threads
#    Must resolve all listed threads before merging (the gate blocks until clean).
#    Work and resolve every listed thread (e.g. via `bro act resolve`/replies),
#    then re-check with `bro act status` until it is green.
npx @broject/bro act merge --bead "$BEAD"  # merge only when green; pass the claimed bead to close it

# 4) Sweep merged threads into debt
npx @broject/bro debt prs          # merged PRs nobody processed yet
npx @broject/bro debt collect      # harvest threads → .agents/review-debt/ + labels
npx @broject/bro debt status       # what's left
npx @broject/bro debt next         # top open finding

As an agent plugin

The repo is a plugin marketplace — one bro plugin packaged per client. The skills tree is identical everywhere; the hook surface differs per host — see the capability matrix:

ClientInstall
Devindevin plugins install ThePlenkov/bro
Claude Code/plugin marketplace add ThePlenkov/bro → /plugin install bro@bro
Codexcodex plugin marketplace add ThePlenkov/bro → install bro
Cursor/add-plugin https://github.com/ThePlenkov/bro, then install bro
OpenCodeadd "plugin": ["@broject/bro"] to opencode.json, or bro plugins install opencode
Kilobro plugins install kilo
pibro plugins install pi

The shell adapters ship session rehydration, the review-gate stop hook, and self-approve for bro/bd — wired through hooks/run.sh, always fail-open. Cursor uses that bus with its own hook schema: context comes back as additional_context, and the stop gate is a single follow-up. OpenCode, Kilo, and pi are native plugins installed by bro plugins install — bro plugins list prints the client × scope matrix. OpenCode has no pre-stop hook, so its stop gate re-prompts once rather than blocking.

On this page