Brat

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.

Site · Docs · Repository

See It In Action

# 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-ui

What 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

Supported AI Coding Engines

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.

How It Works

┌──────────┐         ┌──────────┐         ┌──────────┐
│  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

Web UI Dashboard

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

Quick Start

1. Install

# One-line install
curl -fsSL https://raw.githubusercontent.com/neul-labs/brat/main/install.sh | bash

# Or build from source
cargo install --path crates/brat

Prerequisite: Install Gritee first:

cargo install --git https://github.com/neul-labs/grite grite

2. Initialize Your Repo

cd your-project
grite init     # Initialize Gritee substrate
brat init      # Initialize Brat harness

3. Start the Mayor

# 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

4. Run Agents on Tasks

# Spawn AI agents for queued tasks
brat witness run --once

# Watch progress
brat status --watch

CLI Reference

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.

Daemon (bratd)

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 stop

Features:

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 bratd for 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 900

See docs/bratd.md for full documentation.

Why Brat?

Problems It Solves

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)

What It Doesn't Solve

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

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       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

Workflow Templates

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"

Documentation

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

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/neul-labs/brat
cd brat
cargo build
cargo test

License

MIT License - see LICENSE for details.

Part of the Neul Labs toolchain

Brat is part of the Neul Labs orchestration toolchain:

Project	Description
ringlet	One CLI to rule all your coding agents.
fastworker	Background tasks in Python with zero infrastructure — no Redis, no RabbitMQ.
m9m	The n8n alternative without the bugs — one Go binary.
conductor	Multi-agent CLI orchestrator for AI coding agents.

Learn more at neullabs.com.

Brat is built on Gritee - the append-only substrate for deterministic collaboration.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.brat		.brat
.claude		.claude
.github/workflows		.github/workflows
brat-ui		brat-ui
crates		crates
docs		docs
documentation		documentation
packaging		packaging
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Brat

See It In Action

Supported AI Coding Engines

How It Works

Web UI Dashboard

Quick Start

1. Install

2. Initialize Your Repo

3. Start the Mayor

4. Run Agents on Tasks

CLI Reference

Daemon (bratd)

Why Brat?

Problems It Solves

What It Doesn't Solve

Architecture

Workflow Templates

Documentation

Contributing

License

Part of the Neul Labs toolchain

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Brat

See It In Action

Supported AI Coding Engines

How It Works

Web UI Dashboard

Quick Start

1. Install

2. Initialize Your Repo

3. Start the Mayor

4. Run Agents on Tasks

CLI Reference

Daemon (bratd)

Why Brat?

Problems It Solves

What It Doesn't Solve

Architecture

Workflow Templates

Documentation

Contributing

License

Part of the Neul Labs toolchain

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages