Beads (bd) — Distributed, git-backed graph issue tracker for AI agents
Beads (command-line tool bd) provides a persistent, structured memory layer and task graph tailored to coding agents and multi-agent workflows. Instead of ad-hoc markdown plans, Beads represents tasks as versioned JSONL objects in a .beads/ folder inside a git repository, enabling branching, merging, and history tracking using familiar git workflows.
Key concepts
- Git as database: tasks are stored as JSONL files under
.beads/, making them versioned, branchable and mergeable with standard git operations. - Agent-optimized format: JSON output, dependency links, and automatic detection of "ready" tasks (no open blockers) so agents can query actionable work without parsing free-form text.
- Dependency graph: tasks can express blocks/parent-child/related links, forming a dependency-aware graph for long-horizon planning.
- Zero conflict IDs: hash-based IDs (e.g.
bd-a1b2) reduce merge collisions for multi-agent and multi-branch scenarios. - Local cache & daemon: an SQLite cache accelerates reads; an optional background daemon can auto-sync and reduce contention.
- Semantic compaction (memory decay): closed/old tasks can be summarized to reduce context window usage while preserving essential history.
- Stealth mode:
bd init --stealthruns Beads locally without committing.beads/to the main repo for private or experimental use.
Typical workflow
- Human initializes repository:
bd init(run once by a human admin). - Agents are instructed to use
bdfor task tracking (for example by appending instructions to anAGENTS.md). - Agents create and link tasks programmatically (
bd create "Title" -p 0,bd dep add <child> <parent>). - Agents query actionable items via
bd readyto get tasks with no open blockers. - History, audit trails and merges are handled through git; compaction/summarization reduces long-term context size.
Installation & distribution
- npm:
npm install -g @beads/bd - Homebrew:
brew install steveyegge/beads/bd - Go:
go install github.com/steveyegge/beads/cmd/bd@latest - Requirements: macOS, Linux (glibc 2.32+), FreeBSD, Windows
- Language bindings / packages: there are related packages on npm and PyPI (e.g.
@beads/bd,beads-mcp).
Commands (examples)
bd init— initialize Beads repository metadata (humans run once)bd create "Title" -p 0— create a P0 taskbd dep add <child> <parent>— add dependency linkbd ready— list tasks with no open blockersbd show <id>— view task details and audit trail
Use cases
- Persistent memory for coding agents working across many small changes and long-running projects.
- Multi-agent collaboration where multiple branches and concurrent changes must be merged safely.
- Long-horizon task planning where dependency graphs (blockers, epics, sub-tasks) are necessary.
- Teams that want agent-driven automation but need auditable, versioned records of decisions and actions.
Ecosystem & integrations
Beads ships with community tools and integrations (terminal UIs, web UIs, editor extensions) listed in the repository's documentation. It is distributed via common package managers and provides a workflow that leverages git infrastructure, making it compatible with existing CI/CD and code-review processes.
Limitations & considerations
- Designed primarily as an agent-facing memory/task store rather than a human-first issue tracker; UX and GUIs may be community-provided.
- Uses git as the persistence layer—benefits from git workflows but also inherits git’s operational characteristics (commit/merge semantics, repo size considerations).
License & community
The repository indicates an open-source license badge and maintains documentation (INSTALLING, AGENT_INSTRUCTIONS, TROUBLESHOOTING, FAQ, COMMUNITY_TOOLS). The project has attracted community attention and packages on npm and PyPI for broader adoption.
