Beads: The Graph Database Your AI Coding Agent Actually Needs
Hook
Your AI coding agent is brilliant for 20 minutes, then completely forgets its plan. The problem isn’t the LLM—it’s that we’re asking distributed systems to coordinate using markdown files and hope.
Context
AI coding agents like Claude Code, Cursor, and Aider have a fundamental problem: amnesia. They can generate impressive solutions within a single context window, but the moment they hit token limits, switch branches, or restart a session, they lose track of architectural decisions, pending tasks, and dependency relationships. The current solution—maintaining TODO lists in markdown files—is essentially using plain text as a distributed database, and it fails exactly how you’d expect: merge conflicts when multiple agents work in parallel, no way to claim tasks atomically, and zero understanding of relationships between work items.
Beads, created by Steve Yegge, approaches this as the distributed systems problem it actually is. Instead of treating task tracking as a documentation exercise, it implements a conflict-free replicated data structure backed by Dolt, a version-controlled SQL database. The key insight is that coding agents need structured, queryable memory that survives context resets and supports genuine multi-agent parallelism. This isn’t a productivity tool for humans with a JSON API bolted on—it’s infrastructure built specifically for the way AI agents actually work, with human usability as a secondary concern.
Technical Insight
Beads’ architecture centers on three decisions that make it uniquely suited for agent workflows: hash-based deterministic IDs, Dolt’s cell-level merge resolution, and semantic compaction of closed work.
The ID scheme eliminates coordination overhead entirely. Every task gets a hash-based identifier like bd-a3f8 generated from its content, meaning two agents can create tasks simultaneously without any central coordinator or collision risk. Hierarchical subtasks use dot notation (bd-a3f8.1, bd-a3f8.1.1) to maintain parent-child relationships while preserving the conflict-free property:
# Agent 1 creates a task
$ beads new "Implement auth middleware" --parent bd-a3f8
{"id": "bd-a3f8.1", "status": "open", "title": "Implement auth middleware"}
# Agent 2 simultaneously creates a different subtask—no conflict
$ beads new "Add rate limiting" --parent bd-a3f8
{"id": "bd-a3f8.2", "status": "open", "title": "Add rate limiting"}Under the hood, Beads uses Dolt as its storage layer, which is crucial for multi-agent scenarios. Unlike traditional SQL databases where row-level locking creates coordination bottlenecks, Dolt provides cell-level merge resolution and native branching. When two agents modify different fields of the same task on different branches, Dolt merges them automatically without conflicts. This is the same CRDT-like behavior you’d implement manually in a distributed system, but you get it for free because Dolt treats your database as a git repository:
# Agent 1 on feature-branch claims a task
$ beads claim bd-a3f8.1 --assignee agent-1
# Agent 2 on main adds dependencies to the same task
$ beads depend bd-a3f8.1 --on bd-a3f8.2
# Later, merge both branches—no conflict because different cells changed
$ dolt merge feature-branchThe dependency graph model is first-class in Beads. Tasks aren’t just a flat list with metadata; they’re nodes in a graph where edges represent blocking relationships. This lets agents query intelligently: “What tasks are unblocked and unclaimed?” becomes a graph traversal, not a human reading a markdown file:
# Query for ready work (no blocking dependencies, not claimed)
$ beads list --status open --unblocked --unclaimed
[
{"id": "bd-a3f8.2", "title": "Add rate limiting", "deps": []},
{"id": "bd-b4c9", "title": "Write migration", "deps": []}
]
# After completing bd-a3f8.2, dependent tasks automatically become unblocked
$ beads close bd-a3f8.2
$ beads list --unblocked
[{"id": "bd-a3f8.1", "title": "Implement auth middleware", "deps": ["bd-a3f8.2"]}]Semantic compaction addresses the context window problem directly. As tasks close, Beads can summarize entire completed subtrees into compact descriptions, reducing token usage while preserving essential information. An agent that completed 50 tasks yesterday doesn’t need to load all 50 into context—it can load a single summary node that captures the relevant outcomes. This is memory decay implemented at the infrastructure level.
The JSONL file export provides git portability without Dolt in environments where database installation is impractical. Beads can serialize its entire state to .beads/ directory as line-delimited JSON, giving you a human-readable (and git-diffable) representation that still maintains the graph structure. The tradeoff is you lose cell-level merge resolution and fall back to file-level conflicts, but the hash-based IDs still prevent most collisions.
Gotcha
Beads requires Dolt as a dependency, which significantly complicates deployment compared to a pure Go binary. Dolt itself is excellent software, but it’s another moving part to install, version, and potentially debug across different platforms. If you’re packaging an agent for distribution or running in constrained environments like CI containers, the Dolt requirement becomes a meaningful operational burden. The documentation suggests JSONL fallback mode, but then you lose the cell-level merge resolution that makes multi-agent scenarios actually work—you’re back to hoping git handles your conflicts gracefully.
The project is also relatively young in production usage despite impressive GitHub stars. The multi-agent conflict resolution is theoretically sound, but complex scenarios—like circular dependency detection across branches, or compaction of partially merged task trees—may have edge cases that only emerge with real-world usage. The ‘stealth mode’ feature for maintainers to keep private planning separate from public issues is clever, but the workflow for syncing private task hierarchies with public ones after completion isn’t fully documented. If you’re a maintainer trying to use Beads for internal planning while accepting external contributions, expect to develop your own conventions.
Verdict
Use Beads if you’re building or operating AI coding agents for complex, long-running projects where work spans multiple sessions, branches, or parallel agents. The conflict-free collaboration and dependency tracking pay for themselves immediately in multi-agent scenarios, and the structured memory model is objectively superior to markdown TODOs for any task that takes longer than a single context window. It’s especially valuable in team settings where human developers and AI agents need to coordinate without stepping on each other. Skip Beads if you’re doing simple scripting tasks that complete in one session, working solo on short-lived branches, or operating in environments where installing Dolt is prohibitively difficult. Also skip if you need rich UI visualization for humans—this tool is explicitly optimized for machine consumption, and the CLI-first interface reflects that priority. For traditional project management where humans are the primary interface, stick with Linear or GitHub Issues.
