Gitignored 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).
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.
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
maxRounds
3
Inline 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 /)
docsMaxRounds
2
Tighter round cap for docs-only PRs (every changed file matches docsPaths). 0 disables the docs-specific cap — (maxRounds: 0, docsMaxRounds: 0) is fully uncapped
requireApproval
false
Human-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
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.
Optional command run in each fresh worktree before the agent
stallMin
45
Output-silence advisory in minutes — a live loop agent quiet this long surfaces in bro review watch/bro fleet status. Advisory only; nothing is killed
crashExitMs
10000
An 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
mergeTimeoutMin
45
Review-gate budget in minutes
parkedWakeMin
120
Minutes 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
fixRounds
3
Maximum review-fix respawns per bead
maxItems
0
Maximum beads per run; 0 means until idle or gated
maxOpen
1
Maximum 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
maxOpenTotal
10
Hard ceiling on TOTAL open fleet PRs (work/,loop/,stack/,fix/bro- heads) — claims hold while at or above it; 0 disables
worktreeWarn
40
Linked-worktree count that makes the run warn — hygiene mark only, the reconcile/settle reaps do the shrinking. 0 disables
worktreeMb
400
Estimated disk footprint of one open slot in MB — the disk floor prices every slot at this cost
diskMinSlots
2
Disk floor in slot units — pushes hold while free disk on the worktree parent or tmpdir drops below diskMinSlots × worktreeMb. 0 disables the watermark
batch
1
Max beads one claim may clump into a single work item — one worktree, one worker, one PR closing them all. 1 = solo claims only
batchMinPriority
3
Lowest urgency allowed into a clump — a bead batches only when priority >= batchMinPriority, so urgent work always claims solo
parkedKeep
3
Parked-worktree resume cache cap — the litter sweep keeps at most this many clean parked trees (newest first). 0 = uncapped
parkedTtlDays
14
Days a parked worktree may idle before the litter sweep reaps it regardless of the cap. 0 = no age bound
Cap 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)
routing
unset
Task-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
router
unset
Optional judge classifier — { "provider": "<name>", "mode": "shadow"|"enforce"|"off" } picks the lane for unclassed work
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:
Host-wide live-session quota for that session kind (e.g. agents.devin.maxSessions), admitted under a shared slot lock
agents.<kind>.maxWorkers
unset
Host-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:
Key
Default
What
agents.docker.command
loop.agent
Command run inside the container
agents.docker.image
unset
Image to run; wins over the devcontainer when set
agents.docker.devcontainer
.devcontainer/devcontainer.json
JSONC 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.runArgs
unset
Extra 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:
Key
Default
What
agents.copilot.repo
the worktree's origin remote
owner/repo the task is dispatched against
agents.copilot.base
the repo's default branch
base_ref the task's pull request targets
agents.copilot.model
unset
Model id passed through to the task create call
agents.copilot.customAgent
unset
Custom-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.
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.
Key
Default
What
backend
unset
Named acp provider entry the conductor wires — BRO_PROVIDER_BACKEND wins over config
providers
unset
Other acp entries the gateway routes to by model name — array of entry names or route→entry map
upstream
https://api.anthropic.com
Messages-API base the byte proxy forwards to — BRO_PROVIDER_UPSTREAM overrides
apiKeyEnv
unset
NAMES 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
fastModel
unset
Upstream model id the conductor fast lane rewrites body.model to — BRO_PROVIDER_FAST_MODEL overrides
fastLane
true
false returns every /v1/messages call to the session lane — BRO_PROVIDER_FAST_LANE=off|0|false also disables
idleReleaseMs
300000
Idle window before a pooled acp session releases — 0 disables
client
unset
{ "<name>": { settingsPath, command } } — where bro router client writes the model block and which binary launch execs
acpCwd
unset
Workspace pin for acp sessions when the listener has no repo root (host gateway) — BRO_PROVIDER_ACP_CWD overrides
acpMaxOpens / acpMaxAbandoned
8 / 32
Dead-loop budgets — sessions opened without a completed turn, per conversation and per peer (BRO_PROVIDER_ACP_MAX_OPENS/_MAX_ABANDONED win)
acpStallMs
300000
Silence bound per acp turn — 0 disables the watchdog
acpCooldownMs
60000
Provider-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.