Beads (bd) is a distributed graph issue tracker for coding agents, backed by Dolt, a version-controlled SQL database. It gives an agent persistent, structured memory in place of Markdown plans: tasks live in a dependency-aware graph, so an agent can work through long-horizon jobs without losing track of what is blocked, ready, or done.
The loop is bd create to add a bead, bd ready to list tasks with no open blockers, bd update --claim to take one atomically (assignee plus in_progress), and bd close to finish it, which releases its blockers back into the ready set. bd prime prints workflow context and persistent memories for the agent, and bd remember stores project insights that bd prime injects later. bd init creates or updates AGENTS.md so an agent can discover the workflow, and bd setup installs integrations for Codex, Claude Code, Factory Droid, mux, Cursor, and others.
Dolt runs in-process by default (.beads/embeddeddolt/, single writer) or against an external dolt sql-server for concurrent writers. Cross-machine sync uses bd dolt push and bd dolt pull against refs/dolt/data on the git remote; .beads/issues.jsonl is an export for viewers, not the source of truth. Git itself is optional: with BEADS_DIR set and --stealth, all core commands run without git calls, which suits Sapling or Jujutsu repos, monorepos, CI, and throwaway evaluation databases. A schema version guard stops an older binary from opening a database migrated by a newer one. Runs on macOS, Linux, Windows, and FreeBSD.
Features
- Dependency graph: bd dep add links tasks as blocks, related, or parent-child, and ready work is detected automatically
- Agent-oriented output: JSON output on every command and an audit trail per task via bd show
- Collision-free IDs: hash-based IDs such as bd-a1b2 avoid merge conflicts across agents and branches, with hierarchical IDs (bd-a3f8.1.1) for epics, tasks, and sub-tasks
- Compaction: old closed tasks are summarised to save context window
- Messaging: a message issue type with threading, an ephemeral lifecycle, and mail delegation
- Graph links: relates-to, duplicates, supersedes, and replies-to edges for knowledge graphs
- Roles: bd init --contributor routes planning issues to a separate repo for forks, and maintainer role is detected from the remote URL
- Backup and maintenance: bd export --all, bd backup, bd prune, and bd purge
