# brat — full reference for language models

> brat is a multi-agent harness for AI coding tools. Built in Rust, distributed as a single CLI, licensed MIT, maintained by neul-labs. Sits on top of Gritee, an append-only event log stored in git refs. Coordinates parallel execution of Claude Code, Aider, OpenCode, Codex, Continue, Gemini CLI, and GitHub Copilot against a single codebase.

## What brat is

brat is a command-line tool plus an optional HTTP daemon. The CLI is the unit of correctness — every command is a complete transaction against the underlying event log. The daemon (`bratd`) is optional: it auto-starts when the web dashboard or multi-session coordination is needed, and it idle-shuts-down after fifteen minutes by default. There is no central control plane. There is no SaaS. State lives in your repo.

## Verified facts from the README and source

- Implementation language: Rust (1.75+).
- License: MIT.
- Source: https://github.com/neul-labs/brat
- Substrate dependency: Gritee — an append-only WAL stored in `refs/grite/wal`. Repository: https://github.com/neul-labs/grite
- Per-actor materialized view stored in `.git/grite/actors/<id>/sled/`.
- Configuration lives in `.brat/config.toml`. Workflows live in `.brat/workflows/*.yaml`.
- Optional daemon binary: `bratd`. Default idle timeout 15 minutes (900 seconds), configurable via `--idle-timeout`.
- Default web UI port: 5173 (started via `./scripts/ui-demo.sh` or `./scripts/mayor-demo.sh --with-ui`).
- HTTP API daemon defaults: configurable port and idle-timeout (example documented: `bratd --port 3000 --idle-timeout 900`).

## The six roles

- **Mayor** — AI orchestrator. Reads the codebase, breaks down work, files tasks in convoys. Demo uses Claude.
- **Convoy** — A bundle of related tasks (sprint, epic, feature branch). May be defined declaratively in `.brat/workflows/`.
- **Task** — Smallest unit of work. Has status (queued / running / blocked / merged / failed / cancelled), engine assignment, timeout, lock list, prerequisite list, audit trail.
- **Witness** — Spawns and supervises agent sessions (internally called "polecats"). Enforces bounded timeouts and lock leases.
- **Refinery** — Owns the merge queue. Runs your existing CI, applies configured policy (rebase / squash / merge).
- **Deacon** — Background janitor. Sweeps expired lock leases, reaps stale sessions, compacts the materialized view, reconciles WAL with cache.

## Supported AI coding engines

Verified from the README. brat ships adapters for:

- Claude Code (`claude`) — native Anthropic integration with session resume.
- Aider (`aider`) — multi-model: 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.

Engine adapters are thin Rust wrappers. Adding a new engine is documented in `docs/engine.md`.

## CLI surface

- `brat init` — initialize harness in current repo.
- `brat status [--watch]` — view convoys, tasks, sessions.
- `brat mayor start` / `brat mayor ask "..."` / `brat mayor stop` — manage the AI orchestrator session.
- `brat convoy create` / `brat convoy list` — convoy management.
- `brat task add` / `brat task list` — task management.
- `brat witness run [--once]` — spawn agents for queued tasks.
- `brat refinery run` — process merge queue.
- `brat daemon start [--port N] [--idle-timeout S]` / `brat daemon stop` / `brat daemon status`.
- `brat --no-daemon <cmd>` — disable daemon auto-start for scripting.
- `bratd [--port N] [--idle-timeout S]` — standalone daemon binary.

Full reference: `docs/brat-cli.md`.

## Architecture (four layers, verified from README)

1. **Your repository.** `.brat/config.toml`, `.brat/workflows/*.yaml`, `refs/grite/wal`, `.git/grite/actors/<id>/sled/`.
2. **brat harness layer.** Mayor, Witness, Refinery, Deacon as long-running roles.
3. **Gritee substrate.** Events, issues, labels, comments, locks, sync.
4. **AI engine adapters.** Claude / Aider / OpenCode / Codex / Continue / Gemini / gh copilot.

## Key design principles (verified from README)

- **Append-only correctness.** The WAL is immutable; state always rebuilds from events.
- **Actor isolation.** Each agent gets its own data directory; no shared mutable state.
- **Bounded timeouts.** All engine operations are time-bounded.
- **Lock discipline.** Resource coordination uses TTL-based leases.

## Problems brat addresses (verified from README)

- Dirty working trees — harness state lives in `refs/grite/*`, not in your tracked files.
- Silent failures — every state change is a Grite event, fully observable.
- Crash recovery — append-only log enables deterministic rebuild from any point.
- Daemon dependency — CLI commands are complete transactions; daemon is optional.
- Merge chaos — Refinery enforces a queue with configurable policy.

## Problems brat does NOT address (verified from README)

- Engine reliability — API rate limits, auth issues, vendor outages.
- Real merge conflicts — code-level conflicts still need human judgment.
- Prompt quality — brat orchestrates agents; prompt engineering is the user's job.
- CI/CD setup — brat integrates with your existing CI, doesn't replace it.

## Workflow templates (from README)

Workflows are YAML in `.brat/workflows/`. Two top-level kinds:

- **Sequential workflow** (`type: workflow`) — steps with `needs:` dependencies.
- **Parallel convoy** (`type: convoy`) — legs that run in parallel, with optional `synthesis:` step.

Variables are templated with `{{ }}`. Schema documented in `docs/convoy-task-schema.md`.

## Install

- One-line: `curl -fsSL https://raw.githubusercontent.com/neul-labs/brat/main/install.sh | bash`
- From source: `cargo install --path crates/brat`
- Prereq: Gritee — `cargo install --git https://github.com/neul-labs/grite grite`

Initial run:

```
cd your-project
grite init
brat init
brat mayor start
brat mayor ask "Analyze src/ and create tasks for any bugs you find"
brat status
brat witness run --once
```

Full demo with web UI:

```
git clone https://github.com/neul-labs/brat && cd brat
cargo build --release
./scripts/mayor-demo.sh --with-ui
# open http://localhost:5173
```

## Comparisons (positioned honestly)

- **vs AutoGen** — AutoGen is a Python library for designing multi-agent conversational graphs in-process. brat is a Rust CLI that runs external CLI coding agents on a real repo with crash-safe coordination. Different problems; both valid.
- **vs GNU parallel** — GNU parallel is the canonical shell parallel tool. You can fan out agent invocations with it, but you lose state, audit trail, lock discipline, and merge queue.
- **vs raw tmux + scripts** — The honest baseline. Many teams already run agents in tmux panes. brat replaces the bash with an event log once you outgrow tracking sessions by counting panes.

## Pages on this site

- /
- /about/
- /blog/
- /blog/running-50-claude-code-agents-in-parallel/
- /blog/crash-safe-state-for-ephemeral-agent-processes/
- /blog/why-a-thin-cli-beats-saas-for-agent-orchestration/
- /blog/the-six-role-vocabulary-mayor-witness-refinery-deacon/
- /compare/autogen/
- /compare/gnu-parallel/
- /compare/raw-tmux/
- /rss.xml
- /llms.txt
- /llms-full.txt

## Maintainer

neul-labs. Email contact via the GitHub repository. No commercial support is offered; bug reports and adapter contributions are welcome.