What is Beads?
Beads replaces the markdown to-do lists coding agents keep with a small issue tracker they can query. Each task gets a hash-based ID such as bd-a1b2, tasks link to each other as blockers, parents or duplicates, and `bd ready` lists only the work with nothing open in front of it. An agent claims a task with `bd update --claim`, which sets the assignee and status in one step, and closes it with `bd close`, which frees whatever it was blocking. `bd remember` stores project facts that `bd prime` feeds back at the start of the next session.
Storage is Dolt, a version-controlled SQL database. By default it runs embedded in the CLI with a single writer; server mode connects to a dolt sql-server for several concurrent writers. Machines sync with `bd dolt push` and `bd dolt pull` against a ref on your existing git remote. `bd init` also writes guidance into AGENTS.md and installs hooks for Claude Code, Codex and Cursor. The project moved from steveyegge/beads to the gastownhall organisation; the old path redirects.
Is Beads worth it?
Beads solves a narrow problem well: an agent that forgets on Tuesday what it planned on Monday. Instead of a PLAN.md that drifts out of date, the agent asks `bd ready --json` for unblocked work and records what it finds as new tasks. The repository has about 28,700 GitHub stars, reached v1.0.0 on 3 April 2026 and shipped v1.3.4 on 4 November, with a v1.4.0 release candidate out on 13 November.
The Dolt backend is the reason it merges cleanly. Hash IDs mean two agents on two branches cannot mint the same task number, and Dolt merges rows cell by cell rather than as lines of text. The default embedded mode keeps the database in .beads/ and allows one writer at a time; several agents writing at once need server mode. The .beads/issues.jsonl file is an export for viewers, not a backup, which surprises people who expect plain files in git.
It is quiet by default. OpenTelemetry export is off unless you set BD_OTEL_ENABLED, and model calls happen only in opt-in commands: compaction, which summarises long-closed tasks to save context, and AI duplicate detection both default to Claude Haiku 4.5 on your own Anthropic key (MiniMax is the other supported provider). The project hardens against hostile repositories: a committed .beads/.env cannot set commands or credential helpers, and the experimental HTTP client refuses to send a token over plain http to a non-local server.
The catch: churn. The tracker shows about 1,070 open issues and 697 open pull requests, and upgrades can cross schema migrations that, on a shared database, one designated clone must run before the others bootstrap. Ian Bull, in a long write-up in January, found that Claude ignores Beads unless told to check it and that instructions in CLAUDE.md fade over a long session, so hooks or explicit prompts are still needed.
Our take: for one agent on a short task a markdown checklist is enough; once two agents, two machines or a week-long refactor are involved, Beads keeps the plan in a form the agent can query and git can carry.
Where it earns its place
A solo developer doing a week-long migration with Claude Code
Pick up exactly where yesterday's session stopped
Run `bd init` and let it install the Claude Code hooks; the agent files each discovered problem as a task and `bd prime` restores the open work next morning. No cost beyond the agent itself, since compaction is optional.
A four-person team running agents on separate branches and laptops
Share one task graph without merge conflicts in a plan file
Start a dolt sql-server with `bd init --server` for concurrent writers and sync with `bd dolt push` and `bd dolt pull` against the team's git remote. Upgrades need one person to run the schema migration first, which is worth writing into the team's runbook.
A contributor to an open-source project
Track personal planning without adding files to someone else's repository
`bd init --stealth` keeps Beads local, and `bd init --contributor` routes planning tasks to a separate repository, so pull requests carry only code.
Before you commit
- Setup
- `brew install beads` or `npm install -g @beads/bd`, then `bd init` in the project; it writes AGENTS.md guidance and agent hooks unless you pass --skip-agents or --stealth.
- Integrations
- Claude Code, Codex, Cursor and Factory Droid via `bd setup`; a beads-mcp server on PyPI; JSON output for any agent; an experimental HTTP backend through `bd serve` and `bd connect`.
- Data and privacy
- Tasks live in a Dolt database under .beads/ and sync to a ref on your git remote. Telemetry is opt-in through OpenTelemetry. Compaction and AI duplicate detection send task text to Anthropic or MiniMax only if you run them with a key.
- Cost at scale
- The software is free. Compaction costs Claude Haiku 4.5 tokens; a Dolt server for concurrent writers is your own infrastructure.
- Limits
- Embedded mode is single-writer; schema migrations need coordinated upgrades; the HTTP backend is experimental and refuses some operations; about 1,070 open issues.
What’s good
- `bd ready` gives agents only the unblocked work, as JSON
- Hash IDs and Dolt cell-level merges avoid task collisions across branches
- Syncs through the git remote you already have
- Telemetry off by default; model calls only in opt-in commands
What’s not
- Embedded mode allows a single writer; parallel agents need a Dolt server
- Schema migrations need a coordinated upgrade on shared databases
- About 1,070 open issues and 697 open pull requests
- Agents still need hooks or prompts to use it consistently
Best for
Developers running Claude Code, Codex or several agents on multi-day work who want the plan stored as queryable tasks rather than markdown.
Beads alternatives
Beads: common questions
- Is Beads worth it?
- Beads gives coding agents a task list that survives the end of a session and the merge of a branch, at the price of a database, frequent schema migrations and a busy issue tracker of its own. We rate it 4.0 out of 5.
- How much does Beads cost?
- Free and open source (MIT). Optional compaction and AI duplicate detection call a model on your own Anthropic or MiniMax key.
- What are the downsides of Beads?
- Embedded mode allows a single writer; parallel agents need a Dolt server; schema migrations need a coordinated upgrade on shared databases; about 1,070 open issues and 697 open pull requests; agents still need hooks or prompts to use it consistently.
- Who is Beads best for?
- Developers running Claude Code, Codex or several agents on multi-day work who want the plan stored as queryable tasks rather than markdown.
- How much does Beads cost for a team or in production?
- The software is free. Compaction costs Claude Haiku 4.5 tokens; a Dolt server for concurrent writers is your own infrastructure.
- Is Beads safe for company data?
- Tasks live in a Dolt database under .beads/ and sync to a ref on your git remote. Telemetry is opt-in through OpenTelemetry. Compaction and AI duplicate detection send task text to Anthropic or MiniMax only if you run them with a key.
- What are the best Beads alternatives?
- The closest alternatives we have reviewed are claude-mem, Vibe Kanban and Spec Kit.
Answers checked Nov 13, 2026.
Make Beads? Show this rating on your site
