Beads

// Overview

Beads — the `bd` command — is a distributed graph issue tracker built for AI coding agents, powered by Dolt, the version-controlled SQL database. It exists to replace the sprawling markdown plan files agents tend to write with a dependency-aware graph, so a long-horizon task survives the end of a context window: work is created as beads, linked by dependencies, and `bd ready` returns exactly the tasks that have no open blockers.

The design targets multi-agent and multi-branch work. Hash-based IDs such as `bd-a1b2` avoid merge collisions when several agents create issues at once, Dolt supplies cell-level merge, native branching and sync through Dolt remotes, and `bd update --claim` atomically assigns a task and moves it to in-progress so two agents do not pick up the same work. Hierarchical IDs (`bd-a3f8`, `bd-a3f8.1`, `bd-a3f8.1.1`) express epics, tasks and sub-tasks; graph links (`relates-to`, `duplicates`, `supersedes`, `replies-to`) turn the tracker into a small knowledge graph.

Beads is a CLI you install once and use across projects — the README is explicit that you should not clone the repository into your own. `bd init` sets up a project, writes or updates `AGENTS.md` so agents discover the workflow, and installs integrations; `bd setup` covers Codex, Claude Code, Factory.ai Droid, Cursor, mux and others. Beyond tasks, `bd remember` stores durable project memory that `bd prime` injects back at session start, and compaction summarises old closed work so the context window stays lean. A stealth mode keeps everything local when you would rather not commit tracker files to a shared repo.

// What it does

• Dolt-powered storage: a version-controlled SQL database with cell-level merge, native branching and sync over Dolt remotes
• Dependency graph with `bd ready` auto-detection of claimable, unblocked work, and atomic claiming via `bd update --claim`
• Hash-based IDs (`bd-a1b2`) so parallel agents and branches never collide on issue numbers
• Persistent project memory: `bd remember "insight"` stores it, `bd prime` injects it plus workflow context at session start
• Compaction — semantic memory decay that summarises old closed tasks to save context window
• One-command agent integration through `bd setup` for Codex, Claude Code, Factory, Cursor and more, plus an npm package and a `beads-mcp` PyPI package

// Getting started

Beads is a system-wide CLI available for macOS, Linux, Windows and FreeBSD. Install it once, then initialise it inside each project you want tracked.

brew install beads
# or
npm install -g @beads/bd

cd your-project
bd init

bd setup claude    # Claude Code — hooks/settings
bd setup codex     # Codex CLI — skill, AGENTS.md guidance, hooks
bd setup factory   # Factory.ai Droid — creates/updates AGENTS.md

bd create "Title" -p 0
bd dep add <child> <parent>
bd ready
bd update <id> --claim
bd show <id>
bd close <id>

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Give a coding agent long-horizon work it can resume: a dependency graph of tasks instead of a markdown TODO that falls out of context
• Run several agents or branches against the same backlog without merge collisions on issue IDs
• Keep durable project decisions where the agent will actually see them, via `bd remember` and `bd prime`
• Track personal planning on a shared repository without committing tracker files, using `bd init --stealth`

// How Beads compares

Beads alongside other open-source ai sdlc automation tools AI/TLDR tracks, ranked by GitHub stars.