Beads (the bd CLI) is an issue tracker built for AI coding agents. It replaces markdown plans and TODO lists with a dependency-aware graph of work items (beads), so an agent can pick up long-horizon tasks across sessions without losing context. Agents create beads, query for unblocked work, claim a task atomically, and close it, which releases whatever it was blocking.
Storage is Dolt, a version-controlled SQL database with cell-level merge and native branching. By default Dolt runs in-process with a single writer, and a server mode connects to an external Dolt server for concurrent writers. Sync across machines and agents is a Dolt push and pull over the existing git remote, with no separate server to run. Hash-based IDs prevent collisions when several agents or branches create issues at once, and an experimental HTTP backend lets a workspace act as a thin client against a shared bd serve instance.
Setup commands install hooks, skills, and AGENTS.md guidance for Claude Code, Codex, Cursor, and Factory Droid, and other agents read a short instruction block. Every command emits JSON for programmatic use, and a prime command prints workflow context plus durable project memories that agents stored earlier. Beads also works without git, for non-git version control, monorepos, CI, or throwaway evaluation databases.
For multi-agent work, formulas are declarative workflow templates in TOML or JSON, molecules are work graphs instantiated from them, and gates coordinate asynchronous steps. Gas Town, a multi-agent orchestrator, runs on Beads as its task layer.
Features
- Dependency graph: blocks, parent-child, discovered-from, and related links, with a ready query that lists only unblocked work
- Atomic claiming: an agent claims a task in one step, setting assignee and in-progress status
- Dolt storage: version-controlled SQL with cell-level merge, branching, and sync through Dolt remotes
- Collision-free IDs: hash-based IDs avoid merge conflicts in multi-agent and multi-branch workflows
- Hierarchical IDs: epics, tasks, and sub-tasks share a dotted ID scheme
- Compaction: semantic memory decay summarizes old closed tasks to save context window
- Project memory: agents store durable insights that the prime command injects into later sessions
- Messaging: a threaded message issue type with ephemeral lifecycle and mail delegation
- Graph links: relates-to, duplicates, supersedes, and replies-to edges for knowledge graphs
- Workflows: formulas, molecules, and gates for repeatable multi-agent workflows
- Agent integrations: setup for Claude Code, Codex, Cursor, and Factory Droid, plus an MCP server package
- Stealth and git-free modes: track work locally without committing files or making any git calls
