beads

beads — the crew's shared task board

beads (bd) is a local, git-native, dependency-aware issue tracker (MIT, Go). It is the engineering crew's single source of truth for what work exists, who owns it, what blocks what, and its status — replacing a flat DELIVERY-MAP.md. One issue per node, a real dependency DAG, atomic claiming for concurrent agents, and durable comment threads. Board ownership and the crew workflow live in plugins/engineering/rules/crew-model.md; this skill covers install and operation.

Two surfaces, one board:

• bd CLI (Go binary) — for shell environments; cheapest on tokens.
• beads MCP server (beads/* tools, Python) — shipped by the engineering plugin's .mcp.json, so every crew agent (including shell-less Archie) works the board through MCP tool calls. Same data either way.

---

1. Install

The bd CLI (required — the MCP server shells out to it)

Platform / manager	Command
Homebrew (macOS/Linux)	brew install beads
Install script (macOS/Linux/FreeBSD)	curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
npm	npm install -g @beads/bd
Bun	bun install -g --trust @beads/bd
mise	mise use -g github:gastownhall/beads
Go (server-mode, no CGO)	CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Windows (PowerShell)	irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
Arch (AUR)	yay -S beads-git

The Go module path is github.com/steveyegge/beads (the original repo, kept for module compatibility) even though the repo now lives at gastownhall/beads. Default embedded mode needs no separate Dolt install — Dolt runs in-process, no daemon.

The beads MCP server (how the crew connects)

uv tool install beads-mcp      # recommended
# or: pip install beads-mcp

No API keys, no secrets — all env vars are optional. The engineering plugin already declares the server in plugins/engineering/.mcp.json:

{ "mcpServers": { "beads": { "command": "uvx", "args": ["beads-mcp"] } } }

Installing the engineering plugin gives every crew agent the beads/* tools automatically.

---

2. Initialise in a project (once)

bd init                 # creates .beads/ (embedded Dolt DB + issues.jsonl export)

Git hygiene — commit the interchange export, ignore the binary DB:

# .gitignore
.beads/embeddeddolt/
.beads/dolt/

# commit this — human-readable, diffable interchange log:
.beads/issues.jsonl

.beads/issues.jsonl is an export for review/interchange, not the source of truth — the Dolt DB in .beads/embeddeddolt/ is canonical. Sync across machines with bd dolt push / bd dolt pull.

Wire up the harness (installs session hooks that run bd prime)

bd setup copilot        # GitHub Copilot CLI: .copilot-plugin/plugin.json + .github/copilot-instructions.md
bd setup claude         # Claude Code: SessionStart/PreCompact hooks + CLAUDE.md section
bd setup --list         # all recipes (codex, cursor, windsurf, gemini, aider, …)

---

3. Common operations

MCP tool names (server beads) and their CLI equivalents:

Intent	MCP tool	CLI
Create a task	create	bd create "Title" -p 1 -t task
Add a dependency (A blocks B)	dep	bd dep add <child> <parent>
List unblocked, ready work	ready	bd ready --json
List / filter the board	list	bd list --status open --assignee atlas
Show one task + its deps	show	bd show <id>
Claim atomically (assignee + in-progress)	update	bd update <id> --claim
Update status / priority / notes	update	bd update <id> --status in_progress
Comment (durable, timestamped)	comment	bd comment <id> "…"
Read the comment thread	comments	bd comments <id>
Append a note	note	bd update <id> --notes "…"
See what's blocked	blocked	bd blocked
Project stats / health	stats	bd stats
Close / reopen	close / reopen	bd close <id> "resolution"

Task types: bug, feature, task, epic, chore, decision. Priorities: -p 0..3 (P0 highest). Dependency kinds: blocks, related, parent-child, discovered-from — only open blocks links keep a task out of ready. Hierarchy uses dotted IDs (bd-a3f8.1.1).

Who does what (see crew-model.md for the full contract)

• Archie seeds tasks: requirements in the body, dep links, acceptance criteria, linked docs/architecture/ artefact — no assignee.
• Morgan assigns owners, sets priority, sequences phases (update), keeps the board honest.
• Specialists pull ready work, update --claim it, drive status, comment to coordinate, and mention @archie in a comment to request a design call or new ADR.
• Sherlock reviews at phase boundaries and reopens tasks on divergence.

---

4. Agent session pattern

bd prime                # load board context at session start (wired by `bd setup` hooks)
bd ready --json         # pick unblocked work
bd update <id> --claim  # take it — atomic, prevents two agents grabbing the same task
# …build against the docs/architecture/ artefact the task links…
bd comment <id> "progress / decisions"
bd close <id> "done — contract tests pass"

---

Anti-patterns

Anti-pattern	Why it hurts	Do instead
Tracking work in a flat DELIVERY-MAP.md	No DAG, no status, merge conflicts	Seed the beads board
Archie assigning tasks	Crosses into Morgan's lane	Leave assignee empty; Morgan assigns
Two agents editing the same task blindly	Lost updates	update --claim before working
Committing .beads/embeddeddolt/	Binary churn, conflicts	Gitignore it; commit issues.jsonl
Skipping dep links	ready surfaces blocked work	Wire every hard dependency