How to Use bd (Beads): The Beginner's Guide (First Issue, Ready Work, Dependencies, and MCP)

CodexFuse Team · 2026-11-02T12:09:16.075Z · 15 min read min read

bd (Beads) is a git-native issue tracker built for AI coding agents. This beginner guide covers installing bd, starting a project, creating issues, bd ready, dependencies, and the beads MCP server.

Learning how to use bd (Beads) is the fastest way to give your AI coding agents a memory that survives context compaction, session restarts, and even the agents themselves being swapped out. Beads is a distributed graph issue tracker built for AI agents: issues live inside your repo, link together in a dependency graph, and commit alongside your code — so any agent can pick up exactly where the last one stopped. If you are running coding agents like Claude Code, OpenCode, or Aider on long tasks and keep watching them forget the plan mid-way, this guide walks you from a clean install to a working agent workflow. (If Aider itself is new to you, start with our Aider beginner guide — Aider edits the code, while bd tracks the work, and the two pair well.)

What Is bd (Beads), Exactly?

Beads is a git-native issue tracker whose target user is not human programmers — it is AI coding agents. The README puts it plainly: Beads "provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context." Technically, bd is a single CLI backed by an embedded Dolt database (a MySQL-flavored, version-controlled SQL engine) that lives in a .beads/ directory inside your project. Issues get hash-based IDs like bd-a1b2, which prevent merge collisions when two agents create issues on different branches at the same time. It is open source (MIT) from the gastownhall/beads repository — formerly steveyegge/beads — and it had roughly 28,000 GitHub stars in a mid-October 2026 snapshot, with new releases landing regularly (v1.3.2 was current at the time of writing). This guide teaches how to use beads bd from a clean install to a full agent workflow.

Why Coding Agents Need a beads Issue Tracker

The problem is compaction. A coding agent works through a long task — refactor the auth module, add tests, update the docs — and somewhere around turn 40 its context window fills up and gets compacted. The compacted session remembers "we were working on auth" but drops which of the nine subtasks are done, which are blocked, and what the plan even was. Humans solve this with project boards; agents, left to themselves, solve it with markdown TODO lists that die the moment the session ends. A beads issue tracker gives the agent a memory that outlives the session: every piece of work is an issue with a status and a dependency graph, stored in Dolt, versioned in git. When a fresh agent wakes up, it runs bd ready and instantly sees what is unblocked and safe to start — no briefing meeting required. That instant, zero-handover recovery is the whole point of a beads coding agent workflow.

How to Install bd: 4 Verified Routes

bd ships as a single binary for macOS, Linux, and Windows, and the README documents several install paths. I verified these against the official install sources at write time:

The npm route is what I used for this guide: @beads/bd downloaded beads_1.3.2_linux_amd64.tar.gz from the gastownhall/beads GitHub releases and installed bd globally. One gotcha I hit: extracting the tarball as root failed on file ownership until I re-extracted with tar --no-same-owner — on a normal user account you will not hit this. Verify the install with bd version, which printed bd version 1.3.2 on my machine. A note on the repo name: every current badge, install script, and release points at gastownhall/beads; the old steveyegge/beads path redirects there, and the Go module path keeps the old name "for compatibility with released tags" per the install script's own comment. The bare word "beads" is ambiguous online (jewelry, lab beads, bioscience products), so always search and write with the bd disambiguator.

Starting Your First bd Project: bd init

Run bd init in any directory (a git repo is ideal — if you need a refresher, our Git beginner guide covers the basics). The command creates a .beads/ directory with an embedded Dolt database, installs git hooks, and — this surprised me — creates AGENTS.md and CLAUDE.md files so coding agents can discover the beads workflow on their own. Real output from my sandbox:

Repository ID: 74da81ad
Clone ID: b255b1a490efb95b
Hooks installed to: .beads/hooks/
✓ Created AGENTS.md with agent instructions

Two flags matter for real-world use. bd init --stealth is, in the README's words, for using "Beads locally without committing files to the main repo. Perfect for personal use on shared projects" — it configures git to ignore the beads files so your teammates never see them. And --skip-agents stops bd init from writing AGENTS.md when you manage agent instructions yourself. The command also noted it shares anonymous usage metrics (just command names, version, and OS — never your issues), which you can switch off with bd metrics off.

How Do You Use bd? A Beginner's 5-Step Arc

The whole beads workflow is five commands. Here is the arc I ran locally, end to end, with the real outputs:

1. Create the work. bd create "Add caching layer" -t task -p 2 --json — issue types are bug, feature, task, epic, and chore; priorities run 0 (critical) to 4 (backlog). My sandbox minted the issue as bdsandbox-8ci with status open.
2. Link the dependencies. bd dep add bdsandbox-8ye bdsandbox-8ci — "Write caching docs" now depends on "Add caching layer". The CLI confirmed: ✓ Added dependency: bdsandbox-8ye (Write caching docs) depends on bdsandbox-8ci (Add caching layer) (blocks).
3. Ask what is ready. bd ready — this is the magic one. It printed only the unblocked issue: ○ bdsandbox-8ci P2 Add caching layer, with the footer Ready: 1 issues with no active blockers. The blocked docs issue was invisible until its blocker closed.
4. Claim the task. bd update bdsandbox-8ci --claim — atomically sets assignee and in_progress, so two agents cannot grab the same task. The older equivalent is bd update <id> --status in_progress.
5. Close and move on. bd close bdsandbox-8ci --reason "Caching layer shipped" — and instantly bd ready surfaced the docs issue: ○ bdsandbox-8ye P3 Write caching docs. The blocker released exactly as advertised. Commit the tracker state alongside your code, and let CI be the judge of the actual work — if you need a refresher on automating that, our GitHub Actions beginner guide walks through it.

The Ready-Work Lesson: What bd ready Does

bd ready lists only the issues with no unresolved blockers — the README's exact definition is "List tasks with no open blockers." This is the entire mental model of beads: an agent does not need to read the whole backlog, understand the project, or ask a human what to do. It runs one command and gets the set of tasks that are safe to start right now. The status legend printed under my bd ready run is worth learning: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred, with priorities P0–P4 as labels. For agents consuming this programmatically, bd ready --json -n 0 returns the full JSON payload — my run returned the issue id, title, status, priority, dependency counts, and comment counts in one list. This command is the first thing an agent should run when it wakes up, and the last thing to check before it claims "nothing left to do."

Linking Work with bd dep add

Dependencies are the feature that separates a beads issue tracker from a flat to-do list. bd dep add <child> <parent> declares that the child is blocked by the parent; the relation is the blocks type by default, with related and parent-child types also available. One workflow essay on the technique puts the effect memorably: "The AI literally cannot see abc in bd ready until xyz is closed." Hierarchical epic IDs like bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1 let you nest work, and bd show <id> renders the graph for humans — my run showed a DEPENDS ON section with the linked issue and its status. The practical lesson for agents: file discovered work as you find it, with --deps pointing at the issue that uncovered it. The dependency graph is what lets one agent hand a half-finished 40-issue plan to the next one with zero handover conversation.

bd vs TodoWrite: Why Agents Should Not Use Markdown Lists

Most agent harnesses ship a TodoWrite-style tool: a session-scoped markdown checklist. It works fine for short tasks. The beads vs todowrite question comes up in every agent setup, and here is the honest comparison:

The README is explicit about the intended replacement: Beads "replaces messy markdown plans with a dependency-aware graph," and its AGENTS.md section tells agents directly: "Do not use markdown TODO lists for task tracking." For a quick two-step task, a markdown list is fine. For anything that survives a session boundary, bd is the tool.

bd vs Aider: Tracker vs Code Editor

One line, since this is the most common confusion in the ai-agent-workflow cluster: bd tracks the work; Aider edits the code. Aider is the AI pair-programming tool that writes and modifies files with a git safety net; bd is the issue tracker that remembers which files need writing, in what order, and what is blocked. They are complementary, not rivals — the realistic agent loop is bd ready → claim an issue → edit code with your coding agent (Aider, Claude Code, OpenCode) → close the issue with a reason. Never compare them as alternatives; compare the pair against doing agent work with no memory at all.

CLI or beads mcp? Choosing the Right Interface

Agents that support the Model Context Protocol do not need to shell out to the bd CLI. beads-mcp is the official MCP server: install it with pip install beads-mcp, add it to your client's MCP config (for Claude Code that is ~/.config/claude/config.json), and then call mcp__beads__* tools instead of the CLI. The advantage is direct issue reads and writes without spawning a subprocess, which the integration docs describe as the recommended mode for clients like Claude Desktop. The rule is simple: use beads mcp if your client supports MCP; use the CLI everywhere else. The commands map one-to-one (mcp__beads__ready does what bd ready does), so an agent workflow written against the CLI translates cleanly. One caution from the field: the PyPI package name is beads-mcp — verify you are installing that exact name, since the beads naming collision space is crowded.

How Sync and Storage Work: Dolt Is the Truth, JSONL Is the View

Older write-ups describe beads as "issues in .beads/issues.jsonl that you commit with your code." The current README revises this, and it matters: the embedded Dolt database (.beads/embeddeddolt/ on disk) is the source of truth; .beads/issues.jsonl is an export for viewers and interchange, "not the source of truth or a backup." In v1.3.2, auto-export is even off by default — I had to enable it with bd config set export.auto true, after which a bd create produced the JSONL file (3 lines, one per issue, matching the Dolt data). Cross-machine sync uses bd dolt push and bd dolt pull against refs/dolt/data on your git remote — Dolt remotes and backups, not JSONL import/export, are the sync mechanism. The git hooks installed by bd init handle the local ceremony. If you read an older guide that treats the JSONL file as the database, it is describing a pre-Dolt model; follow the README's Dolt model.

7 Beginner Mistakes with bd

These come from the docs, the agent-skill references, and my own sandbox runs:

Sources

Every fact in this guide was verified from sources fetched for this article. The core mechanic — init, create, dep add, ready, claim, close, and the JSONL export — I ran myself with bd version 1.3.2 on 2026-11-02; quoted CLI outputs are the real terminal output.

• Beads README (gastownhall/beads, fetched live 2026-11-02) — what Beads is, install commands, bd init / --stealth / --skip-agents wording, command table, Dolt-vs-JSONL model, metrics notice, schema-migration guard
• beads install script (raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh, fetched 2026-11-02) — gastownhall rename, "Go module path stays github.com/steveyegge/beads for compatibility with released tags"
• Beads v1.3.2 release assets (github.com/gastownhall/beads/releases, downloaded 2026-11-02) — the binary I verified; npm @beads/bd fetched this release
• eliteai.tools bd-workflow-2 agent skill (fetched 2026-11-02) — exact flags for ready/create/update/close, 7-step agent workflow, MCP integration, "Landing the Plane" ritual; notes it documents the older JSONL-as-truth model
• x-cmd beads install page (fetched 2026-11-02) — "target user is not human programmers — it's AI coding agents"; star snapshot ~25.7k
• asadqi.com beads workflow essay (fetched 2026-11-02) — bd dep add usage and the "AI literally cannot see abc until xyz is closed" framing
• deepwiki beads agent-workflow pages (fetched 2026-11-02) — bd ready definition, TodoWrite deprecation, beads-mcp as recommended MCP mode
• dev.to trending open-source AI projects, October 2026 (GitHub-API snapshot 2026-10-16) — Beads 27,917 stars, MIT license
• beads.gascity.com getting-started/upgrading (referenced 2026-11-02) — documented upgrade flow

Frequently Asked Questions

What is bd (Beads) used for?

bd (Beads) is a git-native issue tracker used by AI coding agents to remember long-horizon work. It stores issues in an embedded Dolt database inside your repo, links them in a dependency graph, and answers one question — bd ready: what is unblocked and safe to start right now. Its target user is AI coding agents, not human programmers, though humans run the agents and write the workflows.

How do I install bd on macOS or Linux?

The recommended route is brew install beads. Alternatives verified from the official docs: the install script (curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash), npm install -g @beads/bd for Node.js users, building from source with Go, an Arch AUR package, or a Windows PowerShell installer. Check with bd version.

What does bd ready do?

bd ready lists only issues with no unresolved blockers — the set of tasks an agent can safely start. Add --json for machine-readable output. It is the first command an agent should run when it wakes up and the last check before it claims there is nothing left to do.

bd vs TodoWrite — which should my agent use?

Use TodoWrite-style markdown lists only for short, single-session tasks. For anything that survives a session boundary, use bd: it persists the dependency graph in git-backed Dolt storage, survives context compaction, supports atomic claim so two agents cannot grab one task, and the README explicitly tells agents not to use markdown TODO lists for task tracking.

Should agents use the bd CLI or beads-mcp?

Use beads-mcp (pip install beads-mcp, then mcp__beads__* calls) if your client supports the Model Context Protocol — it lets assistants read and write issues without spawning a subprocess. Use the bd CLI everywhere else. The commands map one-to-one, so CLI-written workflows translate cleanly.