Beads (bd)

What It Does

Beads is a Go CLI tool (bd) that provides AI coding agents with persistent, structured memory across sessions. It replaces ad-hoc markdown plans and TODO lists with a dependency-aware graph database that agents can query programmatically via JSON output. The core workflow: agents start a session by running bd ready --json to get unblocked tasks, work on them, update status, and the state persists across sessions via git-backed storage.

Under the hood, Beads stores issues in either SQLite (with JSON-L export for git compatibility) or Dolt (a version-controlled SQL database with native branch/merge). Issues have graph relationships (blocks, depends_on, relates_to, replies_to, parent-child hierarchies) and hash-based IDs (bd-xxxx) designed to prevent merge collisions when multiple agents work concurrently.

Key Features

• Dependency-aware task graph: Issues linked by blocks/depends_on/relates_to/replies_to relationships, enabling bd ready to surface only unblocked work
• Hash-based IDs (bd-xxxx): Prevents merge collisions in multi-agent and multi-branch workflows
• Hierarchical epics: Parent-child ID scheme (bd-a3f8 -> bd-a3f8.1 -> bd-a3f8.1.1) for epic decomposition
• JSON output mode: All commands emit structured JSON for programmatic agent consumption
• LLM-powered memory compaction: bd compact uses an LLM to summarize old closed issues, reducing database size while preserving essential context
• Dual storage backends: SQLite (lightweight, JSON-L git sync) or Dolt (version-controlled SQL with cell-level merge)
• Atomic task claiming: bd update <id> --claim for safe concurrent agent assignment
• Stealth mode: Initialize without committing to main repo via bd init --stealth
• MCP server support: Listed on MCP marketplaces for direct agent integration
• Community ecosystem: Third-party TUI viewer (beads_viewer), web interfaces, editor extensions

Use Cases

• Multi-session AI agent workflows: Agents that work on long-horizon tasks spanning days or weeks need persistent memory of what was done, what’s blocked, and what’s next
• Multi-agent coordination: Multiple agents working on the same codebase need collision-free task assignment and dependency tracking
• Solo developer with AI assistant: Developer delegates planning and execution tracking to their coding agent, reviews progress via bd CLI or web UI
• Agentic workflow orchestration: Combined with tools like Claude Code, Sourcegraph Amp, or Cursor to provide structured work queues

Adoption Level Analysis

Small teams (<20 engineers): Fits well. Single binary, MIT license, works embedded in a project repo. The primary audience is individual developers or small teams using AI coding agents. Build complexity (CGO, C compiler) may be a friction point for non-Go developers, but npm/Homebrew installs mitigate this.

Medium orgs (20-200 engineers): Potentially fits for teams heavily invested in AI agent workflows. Multi-agent merge semantics via Dolt become relevant here. However, the tool is young (v0.59.0), the architecture is evolving, and documented migration issues between SQLite and Dolt backends suggest operational risk. No enterprise support or SLA.

Enterprise (200+ engineers): Does not fit today. No commercial support, no RBAC, no audit logging beyond git history, documented database-dropping bugs in server mode. Enterprise teams would need Jira/Linear with API integrations for agent workflows rather than a standalone graph tracker.

Alternatives

Evidence & Sources

• Beads GitHub Repository
• Introducing Beads (Steve Yegge, Medium)
• Beads — Memory for your Agent (Ian Bull, independent review)
• Better Stack: Beads Issue Tracker for AI Agents (independent guide)
• beads_viewer: Graph-aware TUI (community tool)
• Dolt server drops databases after migration (GitHub issue)
• Dolt upgrade experience: issues encountered (GitHub issue)

Notes & Caveats

• Architecture in flux: The project supports two storage backends (SQLite + JSON-L and Dolt) with different trade-offs. The migration path between them has documented bugs including silent database drops in server mode.
• CGO build requirement: Despite marketing as “a single Go binary,” building from source requires CGO, a C compiler, and ICU4c on macOS. Pre-built binaries and npm/Homebrew installs avoid this but limit customization.
• Compaction is lossy: The LLM-powered memory decay feature (bd compact) trades completeness for context window efficiency. No evaluation of information loss quality exists.
• Agent discipline required: Agents do not automatically use Beads — they need explicit prompting in system instructions (AGENTS.md / CLAUDE.md) and can forget to check bd ready mid-session.
• No auto-approve granularity: Claude Code cannot auto-approve only read operations (bd ready, bd show) while requiring confirmation for writes (bd create, bd update) — it is all-or-nothing at the MCP server level.
• Creator built it in 6 days: While this speaks to simplicity, it also indicates the tool’s maturity ceiling. The project is actively developed but remains pre-1.0.
• Dolt performance: The underlying Dolt database is reported to be ~26x slower than PostgreSQL/MySQL in some benchmarks, though for issue tracker workloads (small data, infrequent writes) this is unlikely to matter.