Brigade: A Local-First Ledger for Coding Agent Work, Receipts, and Memory

What Brigade Solves and Who It Targets

Brigade addresses a specific pain: coding agents forget what they did, take the same task twice, and drift out of sync with each other. The README frames it as keeping coding-agent work trackable across tools, repos, and sessions. It targets teams that run multiple agents, possibly on different harnesses, and need a shared record of tasks, verification results, and handoffs. The local-first design means no daemon and no central server for the basic workflow. This suits users who want a lightweight, file-based system that does not require infrastructure. The stable release, v0.30.0 as of October 2026, covers ready work, claim safety, verification receipts, and dry-run-first tool projection, and since 0.27.0 it also includes the optional fleet hub and parallel-safe work waves that earlier shipped only as beta features.

The Core Mechanism: Local JSON Ledger and Atomic Claims

Brigade's foundation is a local JSON ledger that stores tasks and receipts. The README describes the task-store boundary as a local JSON ledger, with an optional hub for events and claims but not as a task database. Atomic claims are the key safety mechanism: two agents cannot take the same item because the claim operation is atomic. The documentation states that Brigade lists unblocked tasks and uses atomic claims so two agents cannot take the same item. This is a fail-closed design, meaning if the claim fails, the agent does not proceed. The ledger is local, so there is no network round-trip for the basic claim operation. This is a deliberate trade-off: you get simplicity and speed, but you lose the ability to share state across machines unless you use the optional fleet hub, which has been part of the stable release since 0.27.0.

Verification Receipts: Command, Exit Code, and Git State

A distinctive feature is the verification receipt. When a check run goes through Brigade, it writes the command, the real exit code, and the Git state. This is not just a log entry; it is structured evidence that a task was completed. The README explicitly warns that not every Brigade command writes a receipt, so you cannot assume all actions produce one. This receipt mechanism feeds into the learning system, which is outcome-based skill scoring, promotion, and rollback. Brigade does not do autonomous reflective memory learning, which is a clear boundary. The receipts are the raw material for scoring: if a command passes and the Git state is clean, the skill gets promoted. This is a concrete, verifiable loop, unlike vague claims of agent intelligence.

Getting Started: Installation and First Commands

Installation is straightforward with either pipx or uv. The README gives two commands: `pipx install brigade-cli` or `uv tool install brigade-cli`. The stable channel is v0.30.0 (`brigade-cli==0.30.0` on PyPI, or `@escoffier-labs/[email protected]` on npm), and it is the recommended install. The beta channel, `brigade update --channel beta`, is an opt-in for development machines that pins the newest daily `0.31.0.devYYYYMMDD` preview wheel built from main. After installation, the README points to QUICKSTART.md and the first-10-minutes guide. The tool is a CLI, so you run it from the terminal, likely inside a repo. The documentation mentions MCP servers, tools, and skills being projected into a harness, with a dry-run-first approach. That means you preview changes before they are written. The exact commands for creating tasks or claiming them are not in the README, so you would need to consult the docs or the quickstart for specifics.

A Genuine Limitation: Local-Only Ledger and Self-Hosted Fleet Features

The biggest limitation is that the core ledger is local-only. If you have agents on different machines, they cannot share the same ledger without the optional fleet hub, which you have to deploy yourself. The README states the hub is for events and claims, not a task DB, so even with the hub you still need a separate source of truth for tasks. Another limitation is that the learning system is not autonomous. It only scores and promotes skills based on receipts; it does not reflect or generate new memories on its own. The README says it is not autonomous reflective memory learning. This means if you expect Brigade to learn from agent behavior without explicit receipts, it will not. Also, the verification receipts are not universal; some commands do not write them, so you cannot rely on them for every action.

How Brigade Compares to Neighbors

The README includes a detailed comparison table. Beads is the closest in terms of claim safety and work orchestration, but it uses a Dolt-backed distributed store, whereas Brigade uses a local JSON ledger. That is a fundamental difference: Beads is distributed by design, Brigade is local-first. nWave uses wave artifacts and phase validation, but it does not document claim safety. Mem0 and Letta are memory-focused, but they do not have the same work-tracking or receipt mechanism. Letta is a persistent agent runtime, which is a different architecture. For tool sync, add-mcp maps fields into native files but warns about dropped fields, whereas Brigade uses a dry-run-first projection with preserve, gate, and rollback. The comparison shows Brigade's niche: it combines work tracking, verification, and tool sync in one tool, but it is not the strongest in any single layer. For example, Beads is stronger on distributed storage, and nWave is stronger on phase validation.

Maintenance and Upgrade Cost

The project is actively maintained, with v0.28.0, v0.29.0 and v0.30.0 all released in October 2026. The update channel mechanism means you can choose between stable and beta. The upgrade path is explicit: `brigade update --channel beta` for the preview. This is a low-friction way to test new features, but it also means you need to be aware of which features are stable. The README states the current stable version and the preview line on main, so you can plan upgrades around feature availability. The license is MIT, which is permissive and allows commercial use. There is no mention of a paid tier or enterprise support, so you are on your own for support. The maintenance cost is moderate: you need to keep the CLI updated and ensure your agents call it correctly. The docs and comparison are dated, which suggests the project is actively documented.

Who Should Adopt It and What to Verify First

Brigade is a good fit for small teams that run agents on a single machine or a shared filesystem, and that need a simple, auditable record of tasks and results. It is also suitable for teams that want to sync tools across harnesses without a heavy server. If you need distributed task coordination, look at Beads. If you need autonomous memory learning, look at Hindsight or Mem0. Before adopting, verify that your harness can call MCP or command-line tools, because Brigade's value depends on integration. Also check which commands write receipts, because not all do. The stable v0.30.0 is the safe choice, and it already includes parallel-safe work waves and the optional fleet hub; the beta channel only makes sense on development machines that want the next preview line. The project is young, so expect breaking changes between minor versions.

Editorial conclusion

Adopt Brigade if you run multiple coding agents across repos and need a fail-closed, local JSON ledger for task claims and verification receipts, and if you prefer a dry-run-first approach to tool projection. Skip it if you need a distributed task store, autonomous reflective memory, or a daemon-based service. Install the stable release, v0.30.0 as of October 2026, which since 0.27.0 also includes parallel-safe work waves, the optional fleet hub and Memory Operations; the beta channel is for development machines tracking the next preview line. Also confirm that your harness can call MCP or command-line tools, because Brigade's value depends on agent integration.

Frequently asked questions

Official sources

1. brigade-cli 0.30.0 on PyPI
2. Brigade v0.30.0 release
3. Official documentation
4. Official README
5. Project repository
6. Release notes