# beads

A CLI issue tracker (`bd`) that gives coding agents a persistent, structured task graph instead of asking them to keep plans in markdown TODO lists. Steve Yegge's project — the storage backend is [Dolt](https://github.com/dolthub/dolt), so the database is version-controlled with cell-level merge and native branching, which is what makes multi-agent and multi-branch workflows survive without merge conflicts. Hash-based IDs (`bd-a1b2`), dependency edges, "memory decay" compaction of closed tasks, and a `bd prime` command that injects workflow context plus persistent memories into the agent's prompt.

## What it replaces

The default state for a coding agent on a long task is a markdown plan that the agent re-reads and rewrites every turn. Beads replaces that with a graph: tasks have IDs, dependencies (`blocks`, `related`, `supersedes`, `duplicates`, `replies_to`, `parent-child`), priorities, and an audit trail. `bd ready` returns the set of tasks with no open blockers — the agent doesn't have to decide what to do next, the graph does. `bd update <id> --claim` is atomic, so two agents on two branches can't claim the same task.

## How it works technically

Storage is Dolt — a SQL database that's also a Git-shaped versioned filesystem. Two modes:

- **Embedded** (default): Dolt runs in-process, data in `.beads/embeddeddolt/`, single-writer with file locking. What `bd init` gives you.
- **Server**: external `dolt sql-server` on TCP (default port 3307) or a Unix domain socket. Multiple concurrent writers. Useful in sandboxed agent setups (e.g. Claude Code) where filesystem ACLs are easier to reason about than firewall rules — that's the actual reason `--server-socket` exists.

The cell-level merge is the load-bearing piece. Two agents editing different fields of the same task on different branches merge cleanly; in plain-text TODO lists the same workflow produces conflicts on every line touched. Hash-based IDs (`bd-a1b2`) avoid the "both agents created issue #42" collision that sequential IDs would have.

Beads is git-aware but doesn't require git. `BEADS_DIR=/path/.beads bd init --stealth` runs entirely without a `.git/` directory, which is what lets it work with [[message-passing-shared-mutable-state|Sapling, Jujutsu, Piper]] or in CI/CD with no repo-level side effects.

The "memory decay" feature is a compaction pass that summarizes old closed tasks into shorter form so the audit trail doesn't blow up the context window. Different mechanism from [[agent-memory-decay|Ebbinghaus-style decay]] in [[hippo-memory]] / [[toolbox/stash|stash]] — beads just summarizes-on-close, no half-life or retrieval strengthening — but the goal (keep the relevant slice in context, fade the rest) is the same.

`bd prime` is the integration surface: agents run it at the start of each session and get back the current workflow rules plus any persistent memories saved via `bd remember "insight"`. `bd setup claude` / `bd setup codex` / `bd setup factory` / `bd setup mux` / `bd setup cursor` write the right `AGENTS.md` or hooks/settings for each harness so the agent knows to call `bd ready` instead of inventing markdown plans.

## Basic usage

```bash
brew install beads
cd your-project
bd init                       # creates .beads/ + AGENTS.md
bd setup claude               # installs hooks for Claude Code

bd create "Fix auth bug" -p 1 -t bug
bd dep add bd-a1b2 bd-c3d4    # bd-a1b2 blocks bd-c3d4
bd ready --json               # what can be worked on now
bd update bd-a1b2 --claim     # atomic claim
bd show bd-a1b2
bd close bd-a1b2 "Fixed in PR #123"

bd remember "deploy script lives in scripts/deploy.sh, takes ~3 min"
bd prime                      # injects context + memories into agent
```

Hierarchical epic IDs: `bd-a3f8` (epic) / `bd-a3f8.1` (task) / `bd-a3f8.1.1` (sub-task).

Contributor vs maintainer split: `bd init --contributor` on a fork routes planning issues to a separate repo (default `~/.beads-planning`) so they don't end up in PRs. Maintainers with SSH or credentialed HTTPS get auto-detected.

## Limitations

- Single-writer in embedded mode — concurrent agents on the same machine need server mode.
- Dolt is the only backend, which means the binary carries Dolt's footprint and you inherit its operational model for `bd dolt push` / `bd dolt pull` sync.
- Server mode auto-start isn't supported when using a Unix socket; you start `dolt sql-server` yourself.
- Windows AV occasionally false-positives on the binary; release checksums are the verification path.

## Related

- [[agent-memory-decay]] — the half-life concept; beads' compaction is a related-but-different point on the same axis.
- [[toolbox/stash|stash]] / [[hippo-memory]] — agent-memory tools; complementary, not replacements (beads is task-shaped, those are memory-shaped).
- [[forge]] — Nesbitt's git-forge abstraction; sits at the same layer (CLI for agents) but for repo/PR/issue ops on GitHub/GitLab/Gitea/Forgejo/Bitbucket. Beads is the local task graph, forge is the remote-forge bridge.
- [[kata]] — the closest direct comparison; same goal (structured task graph for agents, not markdown) but opposite storage philosophy. Beads commits a Dolt database into the repo for branch-merged issues; kata keeps SQLite outside the repo for a clean footprint.

## Repo

[github.com/gastownhall/beads](https://github.com/gastownhall/beads) — Go, MIT, 23.2k stars, v1.0.3, 89 releases. Distributed via Homebrew, npm (`@beads/bd`), and PyPI (`beads-mcp`).