Beads and br solve the same job with two generations of the same idea.
Current Beads uses Dolt as a version-controlled work database, with an embedded single-binary default and a server mode for concurrent writers. br is a Rust reimplementation that deliberately freezes the classic Beads design: SQLite for local queries, JSONL for Git interchange, and no resident daemon.
The choice turns on which contract a project needs to preserve. Current Beads uses one Dolt source of truth, evolves the current protocol and integrations, and has a much larger adoption footprint. br preserves the classic SQLite-and-JSONL contract in a Rust implementation and adds machine-oriented schemas, audit, scheduling, and diagnostic surfaces. Those architectures have different synchronization, compatibility, licensing, and migration consequences.
If the underlying graph model is unfamiliar, why coding agents need a work graph explains the hierarchy, blockers, provenance, and ready frontier both products build on.
Gas City, Inc. publishes this comparison and is the company behind Beads. The page uses the July 12 code-level fork analysis, the July 17 adoption census, and both projects’ public sources, with current Beads behavior rechecked August 1, 2026.
What br preserves
br is not a casual language port. It deliberately preserves the pre-Dolt Beads architecture: a local SQLite database synchronized through a JSONL representation in ordinary Git.
Beads moved away from that design. SQLite and JSONL created two representations that had to stay aligned while agents, worktrees, pulls, merges, deletions, and crashes changed state around them. The project changelog records stale-database overwrites, deleted-issue resurrection, JSONL merge handling, corruption checks, and split-brain failures from that era. Current sync guidance says plainly that JSONL cannot safely reconcile deletes or pruning and is not a backup.
That makes the fork boundary easy to see:
brkeeps SQLite plus JSONL as the operating contract;- current Beads uses Dolt as the only supported database;
bruses ordinary code-repository Git to transport JSONL;- current Beads uses Dolt’s Git-like commit, branch, merge, push, and pull semantics in the work database itself;
bradds separate machine-oriented documentation and command surfaces;- the normal
bdCLI is the agent interface, expanded around command and flag combinations agents actually use.
Compare the current contracts
| Decision factor | Current Beads | br / beads_rust |
|---|---|---|
| Protocol | Actively evolving relationships, integrations, federation, workflow, and onboarding model | Classic Beads issue, dependency, epic, label, and comment model with br extensions |
| Versioned history | Dolt history belongs to the work database itself | Git history covers JSONL snapshots; local SQLite also has snapshots and reconciliation machinery |
| Concurrent operation | Embedded mode for one writer; server mode for several processes sharing one database | SQLite transactions and atomic claim on one local database |
| Cross-machine continuity | Dolt push and pull move database history directly | The user moves JSONL through Git and runs br sync modes |
| Agent surface | Everyday bd commands and flag combinations shaped by observed agent usage | Separate machine-oriented documentation, schemas, capabilities, scheduler, and diagnostics |
| License | MIT | MIT with a rider withholding rights from OpenAI and Anthropic |
| Adoption and ecosystem | Much larger measured distribution, broader integrations, current docs, viewers, and Beads Team Server path | Smaller community centered on classic Beads compatibility and the Rust implementation |
Architecture side by side
| Concern | Beads (bd) | br / beads_rust |
|---|---|---|
| Core job | Durable, vendor-neutral agent work management | Durable agent work management compatible with classic Beads workflows |
| Implementation | Go with embedded Dolt | Rust with SQLite and JSONL |
| Source of truth | One Dolt database | SQLite locally plus JSONL as the Git-facing interchange contract |
| Local default | Embedded Dolt, no server or port | Direct CLI over SQLite, no resident daemon |
| Concurrent writers | Dolt server mode | SQLite transactions and atomic claim on one local database |
| Cross-machine sync | bd dolt push / bd dolt pull move Dolt history | User moves JSONL through Git, then runs br sync modes |
| History | Dolt commit history, branches, merge, and backup | Git history of JSONL plus local snapshots and reconciliation machinery |
| Work graph | Current typed relationships and protocol | Classic Beads issue, dependency, epic, label, and comment model |
| Agent surface | One agent-shaped CLI, integrations, hooks, skills, and current documentation | Separate machine-oriented docs, schemas, capabilities, scheduler, and coordination diagnostics |
| License | MIT | MIT with a rider withholding rights from OpenAI and Anthropic |
The architectures target different compatibility points. br preserves the older sync model; Beads replaced that model with database-native versioning and continued evolving the agent work protocol.
Beads makes work history Git-native
In current Beads, Dolt is not a cache behind a text export. It is the database and the history. The default embedded mode runs inside the bd binary, so a solo user does not need a background server. Server mode is available when several local processes need concurrent writes.
Durable work-state mutations become database commits in embedded mode. Claim leases and heartbeat refreshes are node-local, ephemeral state and create no Dolt history. bd dolt push and bd dolt pull move the durable history through a remote. Cell-level merge handles independent database changes without asking users to reconcile a monolithic JSONL file.
JSONL still exists for interchange and viewers, but current sync guidance does not treat it as the source of truth or a complete backup.
This architecture makes the work graph itself branchable, mergeable, portable, and queryable through its history.
br retains the two-store sync problem
br keeps one SQLite database and a JSONL representation designed to travel through ordinary Git. Its sync command can flush, import, or three-way merge state. Safety guards reject conflict markers, stale databases, and attempts to overwrite non-empty JSONL from an empty database. The CLI does not commit, pull, push, or install Git behavior on the user’s behalf.
Those guards exist because SQLite and JSONL can diverge. Leaving Git commands to the caller does not remove the synchronization problem; it moves responsibility for ordering, freshness, conflicts, and recovery outside the work manager.
br adds machine-readable capability descriptions, separate machine documentation, JSON schemas, an audit log, a scheduler, and coordination diagnostics. Beads uses the regular CLI as the machine interface. Command forms such as bd ready --claim --json and bd update <id> --claim exist because agents needed them in real work, so human and agent callers share one supported command language.
Compatibility and interface tradeoffs
br’s direct compatibility with the classic SQLite-and-JSONL contract can matter to an installation or downstream tool that cannot migrate. Its Rust implementation, separate machine-oriented surfaces, audit log, scheduler, and diagnostics are concrete product capabilities.
That compatibility retains the two-store synchronization problem that caused Beads to move away from the architecture. A br operator must coordinate SQLite, JSONL, and the repository transporting the interchange file. Current Beads instead gives the work database its own commits, branches, merges, remotes, push, and pull through Dolt.
The agent interfaces also reflect different choices. br publishes a separate machine-oriented surface. Beads has been shaped by coding agents using the normal CLI, so human and agent callers share one supported command language.
Both coordinate real work
The comparison is not “database versus task list.” Both products understand dependencies, ready and blocked work, hierarchy, assignment, comments, and atomic claim. Both are intended to survive agent sessions and support swarms.
Current Beads has the broader relationship and operational surface. Parent/child, blockers, provenance, history, integrations, federation, and current agent onboarding evolve as one protocol. br holds closer to classic issue and dependency semantics, then adds its own swarm-oriented tooling.
The command names can also conceal divergence. A similarly named command may not carry the same semantics in both products. For example, br gate implements policy checks on status transitions; current Beads gates are asynchronous wait conditions used by workflow steps. Treat command compatibility as something to test, not infer from spelling.
Migration requires a tested direction
If a project moves from the classic format to current Beads, export a copy, initialize current Beads from the legacy JSONL, compare issue counts and dependency edges, and keep the original store until the Dolt database has been exercised. Modern Beads relationships and history do not round-trip through the classic schema, so test any move in the direction the project intends to keep.
Do not run both CLIs against one live .beads directory as if they shared a storage contract. They do not.
Adoption and ecosystem
br is the only direct alternative with substantial distribution. In the July 2026 review, its public GitHub footprint was well ahead of the smaller alternatives in the direct set.
Beads still led br by a wide margin on both GitHub stars and cumulative release-asset downloads. Beads crossed 800K cumulative GitHub release-asset downloads by July 30. Its npm installer fetches those same release assets, so npm downloads are not added as another installation total. Release-asset downloads include upgrades, automation, and retries rather than unique users; they still show that current Beads has a much larger distribution channel and community surface.
Decide which contract must survive
Current Beads provides Dolt-native history and remotes, the current relationship protocol and integrations, a shared human-and-agent CLI, an unmodified MIT license, and the largest measured ecosystem in the direct set. It requires migrating away from the classic SQLite-and-JSONL storage contract.
br provides classic-format compatibility, a Rust implementation, atomic local claim, and additional machine schemas, audit, scheduling, and diagnostic surfaces. It retains SQLite and JSONL as two representations to reconcile, does not carry current Beads protocol features or Dolt history, and applies a license rider to OpenAI and Anthropic.
Run the same graph through both, sync it to another machine, interrupt a claimed task, and inspect the stores, history, protocol fields, integrations, and license terms. Those facts make the compatibility decision concrete.
Related articles
- Top agent work management systems compared: Place
brand Beads in the full direct competitor set. - Beads: Understand the current work protocol, distribution, integrations, and team path.
- Why coding agents need a work graph: See the relationship model both products inherit.
- Recover agent work after a crash: Test the durability behavior that matters after the storage decision.