Mayor
AI orchestrator that reads your codebase, breaks down work into convoys, and files tasks. Powered by Claude in the bundled demo.
v0 · rust 1.75+ · MIT
run fifty agents
and don't lose your mind.
brat is a multi-agent harness for AI coding tools. It coordinates Claude Code, Aider, Codex, OpenCode and more — in parallel, on the same repo, with crash-safe state and one CLI to drive them.
# install
curl -fsSL https://raw.githubusercontent.com/neul-labs/brat/main/install.sh | bash
# init & run
cd your-project && grite init && brat init
brat mayor start
brat mayor ask "find bugs in src/ and file tasks"
brat witness run --once
how it works
six roles, one event log, zero shared mutable state.
Mayor breaks work into convoys. Convoys hold tasks. Witness spawns agent sessions on those tasks. Refinery merges the result. Deacon sweeps up. Every step writes to the Gritee WAL before it counts.
Convoy
A bundle of related tasks. Think sprint, epic, or feature branch — defined in a yaml workflow.
Task
A single unit of work assigned to a coding agent. Has state, status, and an audit trail in the Gritee event log.
Witness
Spawns and supervises coding-agent sessions (the "polecats"). Handles timeouts, retries, and lock leases.
Refinery
Runs the merge queue. Calls your CI, applies rebase/squash/merge policy, lands work in order.
Deacon
Background cleanup. Releases stale locks, syncs state, detects orphaned sessions, keeps the WAL tidy.
engines
bring your own model.
brat doesn't ship a model. It ships adapters. Configure your preferred engine in .brat/config.toml and the harness handles the rest — session spawn, timeout, log capture, exit-code parsing.
| engine | command | highlights |
|---|---|---|
| Claude Code | claude | Native Anthropic integration, session resume |
| Aider | aider | GPT-4, Claude, Gemini, local LLMs |
| OpenCode | opencode | Open-source Claude Code alternative, 75+ providers |
| Codex | codex | Structured JSON output for parsing |
| Continue | cn | IDE integration, CI/CD pipelines |
| Gemini | gemini | Google's free tier |
| GitHub Copilot | gh copilot | Shell/git command suggestions |
what brat fixes
problems specific to running agents in fleet.
-
Dirty working trees
Harness state lives in refs/grite/*, never in your tracked files.
-
Silent failures
Every state change is a Grite event. Replay the WAL and see exactly what happened.
-
Crash recovery
Append-only log enables deterministic rebuild from any point in the event history.
-
Daemon dependency
CLI commands are complete transactions. bratd is optional; idle-shutdowns after 15 minutes.
-
Merge chaos
Refinery owns the queue with configurable policy (rebase / squash / merge).
what brat doesn't fix
we believe in honest positioning.
There are problems orchestration cannot solve. The README calls them out. So do we.
- Engine reliability — API rate limits, auth issues, vendor outages stay outside brat's control.
- Real merge conflicts — code-level conflicts still need human judgment.
- Prompt quality — brat orchestrates agents; prompt engineering is your job.
- CI/CD setup — brat integrates with your existing CI, doesn't replace it.
architecture
four layers, all auditable.
layer 01
Your repository
.brat/config.toml + workflows in yaml. refs/grite/wal stores the append-only event log. Each actor gets its own sled directory.
layer 02
Harness
Mayor, Witness, Refinery, Deacon — long-running roles that own orchestration, spawning, merging, and cleanup.
layer 03
Gritee substrate
Events, issues, labels, comments, locks, and sync. brat sits on top; everything underneath is one append-only log per repo.
layer 04
Engine adapters
Thin wrappers per coding tool. Claude, Aider, OpenCode, Codex, Continue, Gemini, gh copilot. Adding one is an adapter, not a rewrite.
design principle
Append-only correctness
WAL is immutable. State rebuilds from events. Crashes don't corrupt; they pause.
design principle
Actor isolation
Each agent has its own materialized data directory. Two of them cannot race the same key.
design principle
Bounded timeouts
All engine calls are time-bounded. A hung agent does not block the convoy.
design principle
Lock discipline
Resource coordination uses TTL-based leases. No zombie locks survive a crash.
compare
how it stacks vs the obvious alternatives.
If you're orchestrating coding agents today, you're probably using one of these. Here's where brat fits — and where it doesn't.
vs AutoGen
→Microsoft's multi-agent runtime in Python. Great for conversational agent graphs; less interested in CLI coding tools and crash-safety of long-running sessions.
vs GNU parallel
→The ur-tool for parallel shell. You can absolutely use it to fan out coding agents — but you lose state, audit trail, and merge queue.
vs raw tmux + scripts
→The honest baseline. Many teams already run agents in tmux panes with bash. brat replaces the bash with an event log.
faq
questions before you wire it in.
[+] What is brat actually doing under the hood?
brat sits between you and one or more AI coding agents. It owns the orchestration layer: it spawns agent sessions ("polecats") through the Witness, writes every state transition to an append-only Grite WAL, manages locks with TTL-based leases, and pushes finished work through the Refinery merge queue. Each agent gets its own actor directory so two of them can never trample each other.
[+] Which coding agents does it work with?
Claude Code, Aider, OpenCode, Codex, Continue, Gemini CLI, and GitHub Copilot (shell). The engine selection lives in .brat/config.toml — switch by changing one line. Adding a new engine is an adapter, not a fork.
[+] What does "crash-safe state" actually mean here?
All state changes — tasks created, sessions started, locks acquired, results merged — are written as immutable events to refs/grite/wal before they are considered real. If a process dies mid-step, the daemon (or the next CLI invocation) replays the log and rebuilds the materialized view. There is no "soft" state to lose.
[+] Do I have to run a daemon?
No. The CLI is the unit of correctness — every command is a complete transaction against the WAL. bratd exists for the web dashboard and for multi-session coordination, it auto-starts when something needs it, and it shuts down after 15 minutes of idle by default. You can also disable auto-start with brat --no-daemon for scripting.
[+] Where does the web UI fit in?
There is an optional dashboard that connects to bratd over HTTP. It shows the dashboard cards (queued / running / blocked / merged), convoy and task management, a live log viewer for active sessions, and an interactive Mayor chat. The demo script ./scripts/mayor-demo.sh --with-ui boots the whole thing.
[+] How do workflows work?
YAML files in .brat/workflows/. Sequential workflows declare steps with needs: dependencies; parallel "convoy" workflows declare legs that run in parallel and an optional synthesis step at the end. The schema is documented in docs/convoy-task-schema.md.
[+] Is this for production today?
brat is an open-source CLI under MIT. It is built and tested against real codebases, but you should treat agent-driven changes the same way you treat any unreviewed PR. The Refinery enforces your existing CI gates; the Mayor proposes work, it does not bypass review.
one CLI. many agents. no excuses.
Open source under MIT. Rust 1.75+. Sits on top of Gritee. Runs anywhere you can run cargo.