← home · glossary
the whole vocabulary, in one place.
brat's vocabulary is small on purpose — a small-town transport metaphor plus the substrate that makes it durable. Once you know these terms, every command reads plainly.
The six roles
- Mayor
- The AI orchestrator. Reads the codebase, breaks work down, and files tasks into convoys. The bundled demo runs the Mayor on Claude.
- see also: Convoy · Task
- Convoy
- A bundle of related tasks — think sprint, epic, or feature branch. Can be declared as YAML in .brat/workflows/.
- see also: Task · Workflow
- Task
- The smallest unit of work. Carries a status (queued / running / blocked / merged / failed / cancelled), an engine assignment, a timeout, a lock list, prerequisites, and an audit trail.
- see also: Convoy · Witness
- Witness
- Spawns and supervises agent sessions (internally called "polecats"). Enforces bounded timeouts and lock leases.
- see also: Polecat · Lock lease
- Refinery
- Owns the merge queue. Runs your existing CI, applies the configured policy (rebase / squash / merge), and lands work in order.
- see also: Merge queue · CI gate
- Deacon
- The background janitor. Sweeps expired lock leases, reaps stale sessions, compacts the materialized view, and reconciles the WAL with the cache.
- see also: Lock lease · WAL
The substrate
- Gritee
- The append-only event log brat is built on. Not a database — a chain of immutable events stamped into git refs at refs/grite/wal.
- see also: WAL · Materialized view
- WAL
- Write-ahead log. The immutable, append-only record of every state change, stored in refs/grite/wal. The record of truth; all state is a projection of it.
- see also: Gritee · Replay
- Materialized view
- The per-actor local cache (sled-backed, at .git/grite/actors/<id>/sled/) that each actor reads from. Always derivable by replaying the WAL.
- see also: WAL · Actor isolation
Core concepts
- Polecat
- The internal name for an agent session spawned by the Witness — a scrappy, bounded, disposable worker running one engine against one task.
- see also: Witness · Engine adapter
- Actor isolation
- Each agent gets its own actor data directory, so two agents can never race the same key. There is no shared mutable state.
- see also: Materialized view · Polecat
- Lock lease
- A TTL-based lease used for resource coordination. When it expires it is released, so a crashed session never leaves a zombie lock behind.
- see also: Witness · Deacon
- Bounded timeout
- Every engine operation is time-bounded. A hung agent releases its lease rather than stalling the whole convoy.
- see also: Witness · Lock lease
- Merge queue
- The ordered pipeline the Refinery owns: passing branches land through your CI, one at a time, under your configured policy.
- see also: Refinery · CI gate
- Engine adapter
- A thin Rust wrapper that knows how to spawn one coding-agent binary, handle its session protocol, and parse its output. Adding an engine is an adapter, not a fork.
- see also: bratd · Polecat
- Workflow
- YAML in .brat/workflows/. A sequential workflow declares steps with needs: dependencies; a parallel convoy declares legs that run at once with an optional synthesis step.
- see also: Convoy · Task
Runtime
- bratd
- The optional HTTP daemon. Auto-starts when the web dashboard or multi-session coordination is needed; idle-shuts-down after fifteen minutes by default.
- see also: CLI · Web dashboard
- CLI
- The command-line binary and the unit of correctness. Every command is a complete transaction against the WAL, so even a ctrl-C leaves the system in a defined state.
- see also: bratd · WAL