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 andbro setuprequires it. On GitLab repos the review facade uses an authenticatedglab, butghstays a setup prerequisitebd(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 aroundnpm 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 agentbro 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 findingAs 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:
| Client | Install |
|---|---|
| Devin | devin plugins install ThePlenkov/bro |
| Claude Code | /plugin marketplace add ThePlenkov/bro → /plugin install bro@bro |
| Codex | codex plugin marketplace add ThePlenkov/bro → install bro |
| Cursor | /add-plugin https://github.com/ThePlenkov/bro, then install bro |
| OpenCode | add "plugin": ["@broject/bro"] to opencode.json, or bro plugins install opencode |
| Kilo | bro plugins install kilo |
| pi | bro 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.