← home · how it works
four layers. six roles. one event log.
Everything brat does bottoms out in an append-only event log stamped into your git refs. Here is how a plan turns into merged code, and why a crash anywhere in the pipeline is a pause rather than a loss.
the stack
four layers, all auditable.
┌──────────────────────────────────────────────────────────┐ │ 4 · ENGINE ADAPTERS │ │ claude · aider · opencode · codex · continue │ │ gemini · gh copilot (thin Rust wrappers) │ ├──────────────────────────────────────────────────────────┤ │ 3 · GRITEE SUBSTRATE │ │ events · issues · labels · comments · locks · sync │ ├──────────────────────────────────────────────────────────┤ │ 2 · BRAT HARNESS │ │ Mayor → Convoy → Task → Witness → Refinery → Deacon │ ├──────────────────────────────────────────────────────────┤ │ 1 · YOUR REPOSITORY │ │ .brat/config.toml · .brat/workflows/*.yaml │ │ refs/grite/wal · .git/grite/actors/<id>/sled/ │ └──────────────────────────────────────────────────────────┘
Nothing here is a hosted service. The WAL lives in refs/grite/wal inside your own repository, and each actor reads from a local sled-backed cache it can always rebuild from that log.
the flow
from plan to merged branch.
- 1
Mayor plans
Reads the codebase, breaks work into tasks, files them into a convoy. Writes a "task created" event for each.
- 2
Witness spawns
Picks up queued tasks, spawns an agent session (a polecat) per task in an isolated actor directory, under a bounded timeout and TTL lock lease.
- 3
Engine works
The chosen adapter (Claude Code, Aider, Codex…) runs against the repo and produces a branch. brat captures its logs and exit code.
- 4
Refinery lands
Takes branches that reached merged state, runs your CI, and applies your rebase/squash/merge policy — in order.
- 5
Deacon sweeps
Releases expired leases, reaps stale sessions, compacts the materialized view, and reconciles the WAL with the cache.
Every arrow in that sequence writes an immutable event before the step counts as done. That is the whole trick: the record of truth is the log, so replaying it rebuilds the exact state at any point in history.
design principles
the four rules everything obeys.
Append-only correctness
The WAL is immutable. State is always a projection of events, so it can always be rebuilt. A crash pauses; it never corrupts.
Actor isolation
Each agent has its own materialized data directory. Two agents can never race the same key — there is no shared mutable state.
Bounded timeouts
Every engine operation is time-bounded. A hung agent releases its lease instead of stalling the convoy.
Lock discipline
Resource coordination uses TTL-based leases. No zombie lock survives a crash — the Deacon collects it.
see it run.
The quickstart takes you from install to a merged branch in five commands.