Map

beads

Toolbox toolboxgoai-agentsissue-trackermemorydoltcliGoMIT ↳ show in map Markdown
title
beads
type
toolbox
summary
CLI issue tracker giving coding agents a dependency task graph stored in version-controlled Dolt
tags
go, ai-agents, issue-tracker, memory, dolt, cli
repo
https://github.com/gastownhall/beads
language
Go
license
MIT
created
2026-05-06
updated
2026-05-06

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, 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 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 Ebbinghaus-style decay in hippo-memory / 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

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.
  • agent-memory-decay — the half-life concept; beads' compaction is a related-but-different point on the same axis.
  • 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 — Go, MIT, 23.2k stars, v1.0.3, 89 releases. Distributed via Homebrew, npm (@beads/bd), and PyPI (beads-mcp).

Linked from