Multi-agent harness for AI coding tools. Crash-safe state, parallel execution, one CLI.
Brat is a multi-agent harness that coordinates AI coding tools (Claude Code, Aider, Codex, and more) working in parallel on your codebase. Built on Gritee, an append-only event log, Brat ensures that even if agents crash, your coordination state is always recoverable and auditable.
# Clone and run the full demo with web UI
git clone https://github.com/neul-labs/brat && cd brat
cargo build --release
./scripts/mayor-demo.sh --with-uiWhat the demo shows:
- Creates a sample Python project with intentional bugs
- Starts the Mayor (AI orchestrator powered by Claude)
- Mayor analyzes the codebase and identifies issues by severity
- Mayor creates a Convoy with Tasks for bug fixes
- View everything in the web dashboard at http://localhost:5173
Brat works with your preferred AI coding tool:
| Engine | Command | Highlights |
|---|---|---|
| Claude Code | claude |
Native Anthropic integration, session resume |
| Aider | aider |
Multi-model support (GPT-4, Claude, Gemini, local LLMs) |
| OpenCode | opencode |
75+ LLM providers, open-source Claude Code alternative |
| 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 |
Configure your engine in .brat/config.toml and Brat handles the rest.
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Mayor │─creates─▶│ Convoy │─contains─▶│ Tasks │
│ (AI) │ │ (group) │ │ (work) │
└──────────┘ └──────────┘ └────┬─────┘
│
┌─────────────────────────┘
▼
┌─────────────┐ ┌─────────────┐
│ Witness │─────▶│ Refinery │
│(spawn agents)│ │(merge work) │
└─────────────┘ └─────────────┘
| Role | What It Does |
|---|---|
| Mayor | AI orchestrator that analyzes codebases, breaks down work, and creates convoys/tasks |
| Convoy | A group of related tasks (think: sprint, epic, or feature branch) |
| Task | Individual work item assigned to an AI coding agent |
| Witness | Spawns and monitors coding agent sessions ("polecats") |
| Refinery | Manages the merge queue, runs CI checks, handles integration |
| Deacon | Background janitor: cleans locks, syncs state, detects orphans |
Brat includes a real-time web dashboard for monitoring and control:
- Dashboard - Task status cards (queued, running, blocked, merged)
- Convoys - Create and manage work groups
- Tasks - Filter, assign, and track individual work items
- Sessions - Monitor active AI agents with live log viewer
- Mayor Chat - Interactive interface to communicate with the AI orchestrator
# Start the UI
./scripts/ui-demo.sh
# Opens http://localhost:5173# One-line install
curl -fsSL https://raw.githubusercontent.com/neul-labs/brat/main/install.sh | bash
# Or build from source
cargo install --path crates/bratPrerequisite: Install Gritee first:
cargo install --git https://github.com/neul-labs/grite gritecd your-project
grite init # Initialize Gritee substrate
brat init # Initialize Brat harness# Start AI orchestrator
brat mayor start
# Ask it to analyze your code
brat mayor ask "Analyze src/ and create tasks for any bugs you find"
# Check what it created
brat status# Spawn AI agents for queued tasks
brat witness run --once
# Watch progress
brat status --watch| Command | Description |
|---|---|
brat init |
Initialize harness in current repo |
brat status |
View convoys, tasks, and sessions |
brat mayor start |
Start AI orchestrator session |
brat mayor ask "..." |
Send prompt to Mayor |
brat mayor stop |
Stop Mayor session |
brat convoy create |
Create a new convoy |
brat convoy list |
List all convoys |
brat task add |
Add a task to a convoy |
brat task list |
List all tasks |
brat witness run |
Spawn agents for queued tasks |
brat refinery run |
Process merge queue |
brat daemon start |
Start HTTP API daemon in background |
brat daemon stop |
Stop the daemon |
brat daemon status |
Check if daemon is running |
See docs/brat-cli.md for the complete reference.
Brat includes an HTTP API daemon for the web UI and multi-session coordination:
# Start daemon (auto-starts on most commands anyway)
brat daemon start
# Check status
brat daemon status
# Stop daemon
brat daemon stopFeatures:
- Auto-start - Daemon starts automatically when you run commands that need it
- Idle shutdown - Shuts down after 15 minutes of inactivity (configurable)
- Multi-repo - Single daemon manages multiple repositories
- Standalone binary - Also available as
bratdfor direct invocation
# Disable auto-start for scripting
brat --no-daemon status
# Custom port and longer timeout
brat daemon start --port 8080 --idle-timeout 3600
# Run standalone daemon
bratd --port 3000 --idle-timeout 900See docs/bratd.md for full documentation.
| Problem | How Brat Fixes It |
|---|---|
| Dirty working trees | Metadata lives in refs/grite/*, never in tracked files |
| Silent failures | All state changes recorded as Grite events, fully observable |
| Crash recovery | Append-only log enables deterministic rebuild from any point |
| Daemon dependency | CLI commands are complete transactions; daemons are optional |
| Merge chaos | Refinery manages queue with configurable policy (rebase/squash/merge) |
We believe in honest positioning:
- Engine reliability - API rate limits, auth issues, and vendor outages are outside Brat's control
- Merge conflicts - Real code 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
┌─────────────────────────────────────────────────────────────┐
│ Your Repository │
├──────────────────────────┬──────────────────────────────────┤
│ .brat/ │ refs/grite/wal │
│ ├─ config.toml │ └─ append-only event log │
│ └─ workflows/ │ │
│ ├─ feature.yaml │ .git/grite/actors/<id>/sled/ │
│ ├─ fix-bug.yaml │ └─ local materialized view │
│ └─ code-review.yaml │ │
├──────────────────────────┴──────────────────────────────────┤
│ Brat Harness Layer │
│ ┌────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ │
│ │ Mayor │ │ Witness │ │ Refinery │ │ Deacon │ │
│ └────────┘ └─────────┘ └──────────┘ └────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Gritee Substrate Layer │
│ Events • Issues • Labels • Comments • Locks • Sync │
├─────────────────────────────────────────────────────────────┤
│ AI Engine Adapters │
│ Claude │ Aider │ OpenCode │ Codex │ Continue │ Gemini │
└─────────────────────────────────────────────────────────────┘
Key design principles:
- Append-only correctness - WAL is immutable; state rebuilds from events
- Actor isolation - Each agent gets its own data directory
- Bounded timeouts - All engine operations have configurable timeouts
- Lock discipline - Resource coordination with TTL-based leases
Define reusable workflows in .brat/workflows/:
Sequential workflow (feature.yaml):
name: feature
type: workflow
steps:
- id: design
title: "Design {{feature}}"
- id: implement
needs: [design]
title: "Implement {{feature}}"
- id: test
needs: [implement]
title: "Test {{feature}}"Parallel convoy (code-review.yaml):
name: code-review
type: convoy
legs:
- id: correctness
title: "Review correctness"
- id: security
title: "Review security"
- id: performance
title: "Review performance"
synthesis:
title: "Synthesize review findings"| Document | Description |
|---|---|
| Architecture | System design and data flow |
| CLI Reference | Complete command documentation |
| Daemon (bratd) | HTTP API daemon and auto-start |
| State Machine | Session lifecycle and transitions |
| Roles | Mayor, Witness, Refinery, Deacon |
| Engine Integration | Adding new AI engines |
| Workflows | Convoy and task schemas |
| Roadmap | Current status and planned features |
We welcome contributions! See CONTRIBUTING.md for guidelines.
# Development setup
git clone https://github.com/neul-labs/brat
cd brat
cargo build
cargo testMIT License - see LICENSE for details.
Brat is built on Gritee - the append-only substrate for deterministic collaboration.