docs

Configuration

bro.config.ts — typed config, validated sections, safe fallbacks.

Config lives in three merged layers — precedence local > project > global:

LayerFileAudience
global$XDG_CONFIG_HOME/bro/config.{ts,json} (default ~/.config/bro/)Your cross-project operator config — providers, judge, fleet, agents
projectbro.config.{ts,json} in the repo rootCommitted, identical-for-everyone policy — act, sdd, guard, debt, stack
localbro.config.local.{ts,json} in the repo rootGitignored project-private overrides — machine paths, personal caps

Each layer resolves cwd → main worktree root (linked worktrees inherit), .ts shadows .json in one dir. Layers deep-merge: objects merge per key, arrays and scalars replace — a layer only needs the keys it sets. bro doctor prints the effective layers, per-section provenance, and warns when operator config sits in the committed file or policy sits in the global one (advisory — loading never drops a section for being in the "wrong" layer).

// bro.config.ts — plain default export; every key optional
export default {
  personality: 'terse',
  stores: ['jsonl', 'beads'],
  debt: { dir: '.agents/review-debt' },
  sync: { ref: 'refs/bro/data', remote: 'origin', beads: true },
  act: { ignoreChecks: ['kilo'], maxRounds: 3 },
  plugins: ['./my-plugin.ts'],
};

bro setup writes bro.config.local.json — store choices are machine-local and never belong in the committed layer.

Sections

stores

Artifact backends. jsonl is the evidence ledger — always written. beads is on by default (auto-inits .beads stealth when missing — announced on stderr, skipped on dry/list-only/empty-ledger runs, nothing lands in git) and projects debt into bd. gitref pushes artifact dirs to the data ref. Explicit "stores": ["jsonl"] is the beads opt-out.

debt

KeyDefaultWhat
dir.agents/review-debtLedger directory (BRO_DEBT_DIR env wins)

sync

KeyDefaultWhat
refrefs/bro/dataData ref — outside refs/heads, never a branch
remoteoriginRemote the data ref pushes/pulls
beadstrueAlso run bd sync — beads state (drill frames, wtfs, retros) has its own transport; false syncs only bro artifacts

act

KeyDefaultWhat
ignoreChecks[]Advisory checks excluded from the exit gate — for chronically flaky external reviewers. Entries are name substrings or { name, consecutiveFailures, threadWindowDays } (defaults 3, 7): a failing check stays quiet only after that many consecutive failing heads with matching thread activity — otherwise it surfaces as a non-blocking alert. A scanner name (sonarcloud, codescene) overrides its must-fix default
selfCheck""Name of the check that IS the gate — the gate never counts itself. Empty means "no self check". Set it when the gate is published as a project-side required check: while the gate job runs, its own check is pending on the PR head, and a gate that counts itself can never settle green. Matched by NAME (case and separators normalize), not by substring — an unrelated check that merely contains the name is never dropped from the gate
maxRounds3Inline fix-round cap. Past it, remaining threads must defer to debt beads. 0 unbounds non-docs PRs — a docs-only PR is still capped while docsMaxRounds > 0
docsPaths['*.md', '*.mdx', '*.rst', 'docs/']Path patterns classifying a file as docs. No slash → basename glob (*.md); trailing / → dir at any depth, name globs too (docs*/ hits docs-v2/); otherwise full-path glob (** crosses /)
docsMaxRounds2Tighter round cap for docs-only PRs (every changed file matches docsPaths). 0 disables the docs-specific cap — (maxRounds: 0, docsMaxRounds: 0) is fully uncapped
requireApprovalfalseHuman-signoff gate: when true, the exit gate — and every auto-merge driven off it (bro review drive, bro review act merge, watch/loop merge paths) — additionally requires a trusted human's approving review on the PR's current head. Semantics: the latest decision review per reviewer decides; a standing CHANGES_REQUESTED vetoes regardless of which head it reviewed; bot approvals never count; a probe that can't answer reads as not approved, never a pass. Opt-in hostile-input hardening — a malicious bead or prompt-injected agent cannot satisfy it on its own. Default false keeps bot-only auto-merge — in that mode the hardening is drive.merge: 'never' plus host branch protection
approvers[]Trusted reviewer logins for requireApproval — when non-empty, only approvals from these accounts count (case-insensitive). Empty means any human (User) account's current-head approval counts. The knob that keeps a machine user account from signing off on the agent's own output

plugins

External plugin specifiers — relative paths (contained to the repo) or package names, imported at startup. Each module's default export must be a BroPlugin. See Plugins.

loop

KeyDefaultWhat
agent""Shell template for the agent command; {promptFile} is replaced by the work order. The raw lane — superseded by provider/profile
provider""Named provider the spawn resolves through — acp entries run the headless acp-worker, cli entries substitute their command for agent
profile""fleet.profiles.<name> preset — fills provider/model/autoApprove piecewise
model""Model override for the provider lane
bootstrap""Optional command run in each fresh worktree before the agent
stallMin45Output-silence advisory in minutes — a live loop agent quiet this long surfaces in bro review watch/bro fleet status. Advisory only; nothing is killed
crashExitMs10000An agent exit faster than this is an environment crash — the bead parks loud instead of reopening into a respawn-burn. 0 restores legacy reopen-on-every-exit
mergeTimeoutMin45Review-gate budget in minutes
parkedWakeMin120Minutes a parked bead stays deferred before the next ready-front read wakes it to open — the claim-side park TTL. 0 ices the bead until bd undefer
fixRounds3Maximum review-fix respawns per bead
maxItems0Maximum beads per run; 0 means until idle or gated
maxOpen1Maximum open PRs on the run's gate stack — a full stack only services gates until a merge frees a slot. Serial by default; widen with --max-open
maxOpenTotal10Hard ceiling on TOTAL open fleet PRs (work/,loop/,stack/,fix/bro- heads) — claims hold while at or above it; 0 disables
worktreeWarn40Linked-worktree count that makes the run warn — hygiene mark only, the reconcile/settle reaps do the shrinking. 0 disables
worktreeMb400Estimated disk footprint of one open slot in MB — the disk floor prices every slot at this cost
diskMinSlots2Disk floor in slot units — pushes hold while free disk on the worktree parent or tmpdir drops below diskMinSlots × worktreeMb. 0 disables the watermark
batch1Max beads one claim may clump into a single work item — one worktree, one worker, one PR closing them all. 1 = solo claims only
batchMinPriority3Lowest urgency allowed into a clump — a bead batches only when priority >= batchMinPriority, so urgent work always claims solo
parkedKeep3Parked-worktree resume cache cap — the litter sweep keeps at most this many clean parked trees (newest first). 0 = uncapped
parkedTtlDays14Days a parked worktree may idle before the litter sweep reaps it regardless of the cap. 0 = no age bound

drive

KeyDefaultWhat
intervalSec300Cadence for --every and scheduled --once runs
merge"auto"auto merges orphaned green PRs; never reports them without merging

fleet

KeyDefaultWhat
maxConcurrent3Cap on live registry agents, counted across all backends. 0 is uncapped. Enforced in the shared spawn prologue under the registry lock; an unverifiable entry occupies its slot (fail-closed)
routingunsetTask-class → ordered provider-chain table. bro loop and bro agents up resolve each bead's class:<name> label (or default) to a chain; the head supplies the provider unless a flag already pinned one
routerunsetOptional judge classifier — { "provider": "<name>", "mode": "shadow"|"enforce"|"off" } picks the lane for unclassed work

agents

agents contains object-valued backend-specific configuration bags. Their keys are defined by the selected backend; there is no universal backend option set or schema default. Choose the backend under connectors.agents, not agents. Two cross-backend keys exist:

KeyDefaultWhat
agents.<backend>.providerunsetNamed provider the backend's spawns run through
agents.<kind>.maxSessionsunsetHost-wide live-session quota for that session kind (e.g. agents.devin.maxSessions), admitted under a shared slot lock
agents.<kind>.maxWorkersunsetHost-wide quota counting only spawned sessions of the kind — interactive sessions never consume this budget. The plane must distinguish workers (devin: BRO_AGENT_ID env badge or a non-terminal stdin); arming it on a plane that cannot refuses loudly

The docker backend (connectors.agents: "docker" or --connector docker) runs each worker in a container with the worktree, git common dir and beads store mounted at their host paths:

KeyDefaultWhat
agents.docker.commandloop.agentCommand run inside the container
agents.docker.imageunsetImage to run; wins over the devcontainer when set
agents.docker.devcontainer.devcontainer/devcontainer.jsonJSONC devcontainer file, repo-relative or absolute. Its image is used directly (pulled before spawning when absent); build.dockerfile is rebuilt on every spawn — docker's layer cache makes a no-op build fast — under a content-hash tag (bro-dev-<sha256/12>). dockerComposeFile configs are unsupported — set agents.docker.image for those
agents.docker.runArgsunsetExtra docker run arguments — array or whitespace-split string (e.g. ["--network", "host"]). Containers default to the host --user uid:gid so bind-mounted files stay host-owned; set -u/--user here to override

The copilot backend (connectors.agents: "copilot" or --connector copilot) dispatches GitHub Copilot coding-agent tasks — hosted remote workers that push a branch and open a pull request. It needs no local worktree or agent command (a provider-resolved worker is refused); gh on PATH is the only prerequisite:

KeyDefaultWhat
agents.copilot.repothe worktree's origin remoteowner/repo the task is dispatched against
agents.copilot.basethe repo's default branchbase_ref the task's pull request targets
agents.copilot.modelunsetModel id passed through to the task create call
agents.copilot.customAgentunsetCustom-agent name passed through to the task create call

agents.copilot.maxSessions/maxWorkers cap the account's remote live tasks through a cached-count session plane — connector reads refresh the cache and a stale/absent one fails closed (unavailable), so an unreachable GitHub API refuses rather than overspends.

providers

The named provider registry — { "<name>": { "type": "api"\|"acp"\|"cli", …connection } }. Consumers pick by name; the entry's kind fixes the connection shape (api: baseUrl + apiKeyEnv/apiKeyCommand + models allowlist; acp/cli: command + model). See Providers.

judge

KeyDefaultWhat
mode"off"off decides nothing on its own; shadow annotates act threads and journals verdicts
provider / modelunsetNamed provider + allowed model id the chain resolves through
fallbackunsetEscalation provider name re-asked on unanswered or low-confidence answers
confidence0.6Confidence floor below which answers escalate
timeoutMs3000Bounds the whole chained call
maxDecisionsPerRun50Fresh decide() calls per invocation
baseUrl / apiKeyEnv / llmunsetLegacy single-backend shape — synthesized into anonymous api providers with a deprecation warning

serve

The bro serve/bro provider serve host's own knobs. Two planes read it: the acp conductor (backend/providers) and the /v1/* byte proxy (upstream/apiKeyEnv) — config owns the URL and the credential's env-name; env stays the override + secret channel.

KeyDefaultWhat
backendunsetNamed acp provider entry the conductor wires — BRO_PROVIDER_BACKEND wins over config
providersunsetOther acp entries the gateway routes to by model name — array of entry names or route→entry map
upstreamhttps://api.anthropic.comMessages-API base the byte proxy forwards to — BRO_PROVIDER_UPSTREAM overrides
apiKeyEnvunsetNAMES the env var holding the real upstream credential (SCREAMING_SNAKE) — BRO_PROVIDER_API_KEY/ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN override it. The key itself never sits in config
fastModelunsetUpstream model id the conductor fast lane rewrites body.model to — BRO_PROVIDER_FAST_MODEL overrides
fastLanetruefalse returns every /v1/messages call to the session lane — BRO_PROVIDER_FAST_LANE=off|0|false also disables
idleReleaseMs300000Idle window before a pooled acp session releases — 0 disables
clientunset{ "<name>": { settingsPath, command } } — where bro router client writes the model block and which binary launch execs
acpCwdunsetWorkspace pin for acp sessions when the listener has no repo root (host gateway) — BRO_PROVIDER_ACP_CWD overrides
acpMaxOpens / acpMaxAbandoned8 / 32Dead-loop budgets — sessions opened without a completed turn, per conversation and per peer (BRO_PROVIDER_ACP_MAX_OPENS/_MAX_ABANDONED win)
acpStallMs300000Silence bound per acp turn — 0 disables the watchdog
acpCooldownMs60000Provider-wall cooldown — how long a lane stays closed after the account refused; 0 disables

bro provider serve reads this section at the global layer only — a repo's committed config never redirects the machine-wide listener's upstream. Repo-scoped bro serve reads the full merge.

guard

KeyDefaultWhat
enabledtruefalse silences the whole mechanism
defs[]Project-owned guard declarations — { name, when, say }; shadow a builtin by reusing its name
maxPerEvent—Cap on guard lines one hook event emits

See bro self guard for the when clause vocabulary.

query

KeyDefaultWhat
concurrency4Fan-out cap for query plan steps
env{}Operator-pinned literal env overlay for connector spawns

sweep

KeyDefaultWhat
olderThanDays30Age line for both the gate and bd prune --older-than
dir.agents/sweepArchive directory — must live inside the synced set so bro work sync carries it
flattentrueRun bd flatten as the pipeline's last stage

learn

KeyDefaultWhat
enabledtrueDisable lesson injection without deleting the store
maxInject3Maximum lesson lines emitted by one hook probe
sources[]Empty means all lesson sources; a non-empty list is an allowlist

sdd

KeyDefaultWhat
mode"off"off, remind, or gate; gate blocks once at the stop hook
dir"specs"Directory used by the native specs connector

watch

KeyDefaultWhat
intervalSec60Heartbeat cadence for bro review watch install

check

KeyDefaultWhat
binunsetSverka executable or path
configunsetSverka config path
entryunsetSverka entry name
executorunsethost or docker
evaluatefalseCollect SARIF artifacts and run the policy gate

drill

KeyDefaultWhat
report.dir"drills"Repo-relative directory for durable drill reports
report.mode"off"off, prompt, or always; explicit --report still wins

stack

KeyDefaultWhat
mode"manual"manual stacks only on explicit --stack/--base; auto uses the current worktree branch when appropriate

beads

KeyDefaultWhat
global~/.local/share/bro/beadsUser-level beads directory; BRO_GLOBAL_BEADS overrides the file value, and ~ expands to the home directory

On this page