bro

Why

Review bots dump comments on your PRs. You merge, the threads stay unresolved, the findings evaporate. Your agent can read a PR — but can it tell which merged PRs still have review threads rotting in them? Can it say “what’s left” — without burning a thousand tokens re-reading every comment to find out?

Now it can. bro is a token-efficient orchestration layer: it keeps the project’s state outside the context window — in beads — and answers workflow questions in one command instead of a context-draining fetch loop.

The token math

Every bro command is a workflow an agent would otherwise hand-roll with dozens of tool calls — re-fetching data it already fetched, re-reasoning about state it should have just remembered.

The review loop — bro act

Without bro — each iteration the agent re-reads everything:

calls  ≈ pushes × (PR + threads + checks + mergeable)
context ≈ every comment body, every check log, every round
stop   = a feeling

With bro — one command, one verdict:

$ bro act status
open_threads=2 ci_pending=0 fix_rounds=2
exit_gate=BLOCKED
  blocker: 2 unresolved review thread(s)

Frustration — bro wtf → bro retrospect

Without bro — you vent, the agent apologizes, nothing is recorded. Next sprint, same mistake.

With bro — high-level frustration escalates into a self-learning retrospection mechanism:

bro wtf "why did you leave red??"
  → wtf bead (verbatim + git snapshot)
bro retrospect record retro.toml
  → retro bead + prevention beads
  → prevention lands in AGENTS.md / CI / skills

Project memory — debt, drill, sync

Without bro — every agent invents its own ledger format, keeps it in chat, and loses it on compaction.

With bro — beads-backed state that survives sessions:

bro debt collect    # merged-PR findings → ledger + beads
bro drill down      # investigation frames = beads
bro sync            # it all lives on refs/bro/data

What bro is

Not a fixer — a memory and a gate. Every capability ships the same way: a command, a skill, a config section, a plan schema. One plugin install gives the same mechanics to Devin, Claude Code, and Codex.

Review debt

bro debt harvests unresolved threads on merged PRs into a ledger — nothing scanned twice, nothing hidden.

Exit gate as code

bro act status counts threads, CI, SAST, fix rounds. Non-zero while blocked; bro act merge refuses to bypass it.

Scoped descent

bro drill frames a problem and ascends only with --result — plus prevention beads so it doesn’t recur.

Extensible by contract

definePlugin — own command, config section, plan schema. Bring your own memory; bro hosts it.

How

Commands infer context — you mostly don’t pass arguments at all:

bro act         # on a branch → the gate for its PR
bro debt        # the damage report
bro drill       # where the current descent stands
bro wtf "..."   # vent → bead; bare → what's unanswered

npx -y @theplenkov/bro setup        # wire bro into the repo

bro collects and carries — the verdict is yours. bro got you.