Beads (bd)

Beads (CLI: bd) is an open-source, distributed graph issue tracker built specifically for AI coding agents. Developed by the gastownhall organization and written in Go, it replaces ad-hoc markdown plans with a version-controlled, dependency-aware task graph backed by Dolt — a Git-like SQL database. The project reached v1.0.4 as of May 2026 and has accumulated over 23,000 stars on GitHub according to the repository metadata.

What It Is

Beads is a CLI tool that gives coding agents persistent, structured memory across long-horizon tasks. Instead of losing context between sessions or relying on fragile markdown TODO lists, agents interact with a Dolt-powered SQL graph that tracks tasks, dependencies, priorities, and project memories. The core command set (bd ready, bd create, bd update, bd close, bd prime, bd remember) is designed to be called directly by agents like Claude Code, Codex CLI, Factory.ai Droid, Cursor, and others.

How the Agent Memory Model Works

The central concept is a dependency-aware issue graph where tasks carry hash-based IDs (e.g., bd-a1b2) to prevent merge collisions in multi-agent or multi-branch workflows. Key design choices include:

• bd prime injects workflow context and persistent project memories into the agent's context window at the start of a session.
• bd remember "insight" stores durable project knowledge that survives session boundaries.
• Compaction applies semantic "memory decay" to summarize old closed tasks, preserving context window budget.
• Hierarchical IDs support epics, tasks, and sub-tasks (bd-a3f8, bd-a3f8.1, bd-a3f8.1.1).
• Graph link types (relates_to, duplicates, supersedes, replies_to) enable knowledge graph construction.

Storage Architecture

Beads uses Dolt as its database engine in two modes. Embedded mode (default) runs Dolt in-process with no external server; data lives in .beads/embeddeddolt/ and is single-writer with file locking. Server mode connects to an external dolt sql-server and supports multiple concurrent writers. Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data. A .beads/issues.jsonl export exists for interchange and backup but is not the source of truth. Git-free usage is also supported via the BEADS_DIR environment variable and --stealth mode, making Beads usable in CI/CD, monorepos, and non-git VCS environments like Sapling or Jujutsu.

Agent and IDE Integration

Beads ships first-class setup commands for major agent environments:

• bd setup claude — installs hooks and settings for Claude Code
• bd setup codex — creates/updates AGENTS.md for Codex CLI
• bd setup cursor — configures Cursor IDE
• bd setup factory — targets Factory.ai Droid
• bd setup mux — for mux-based workflows

For unsupported agents, bd onboard prints a minimal snippet to paste into any agent instruction file. An MCP server is also available via the beads-mcp PyPI package, and an npm package (@beads/bd) is published for Node.js users.

Update: v1.0.4

The repository metadata shows the latest release is v1.0.4, published May 9, 2026, with the last push on May 18, 2026 — indicating active development. The project was created in October 2025 and has grown rapidly, with the repository listing 346 open issues and 1,577 forks. Installation is available via Homebrew (brew install beads), npm, an install script, go install, and AUR for Arch Linux. Windows 11 is also supported with antivirus false-positive guidance documented.