Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction.

Overview

bd (beads) replaces markdown task lists with a dependency-aware graph stored in git.

Key Distinction:

bd: Multi-session work, dependencies, survives compaction, git-backed
Task tools (TaskCreate/TaskUpdate/TaskList): Single-session tasks, status tracking, conversation-scoped

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Operating Rules

Treat live bd reads as authoritative. Use bd show, bd ready, bd list, and bd export to inspect current tracker state. Do not treat .beads/issues.jsonl as the primary decision source when live bd data is available.
Treat .beads/issues.jsonl as a git-friendly export artifact. If the repo tracks .beads/issues.jsonl and you mutate tracker state, refresh it explicitly with bd export -o .beads/issues.jsonl.
After closing or materially updating a child issue, reconcile the open parent in the same session. Update stale "remaining gap" notes immediately, and close the parent when the child resolved the parent's last real gap.
If bd ready returns a broad umbrella issue, do not implement directly against vague parent wording. First narrow the remaining gap into an execution-ready child issue, then land the child and reconcile the parent.
Normalize stale queue items instead of silently skipping them. Rewrite broad or partially absorbed beads to the actual remaining gap.
Use this post-mutation sequence when tracker state changed:

bd ...                              # mutate tracker state
bd export -o .beads/issues.jsonl    # if tracked in git
bd vc status
bd dolt commit -m "..."             # if tracker changes are pending
bd dolt push                        # only if a Dolt remote is configured

Prerequisites

bd CLI: Version 0.34.0+ installed and in PATH
Git Repository: Current directory must be a git repo
Initialization: bd init run once (humans do this, not agents)

Examples

Skill Loading from /vibe

User says: /vibe

What happens:

Agent loads beads skill automatically via dependency
Agent calls bd show <id> to read issue metadata
Agent links validation findings to the issue being checked
Output references issue ID in validation report

Result: Validation report includes issue context, no manual bd lookups needed.

Skill Loading from /implement

User says: /implement ag-xyz-123

What happens:

Agent loads beads skill to understand issue structure
Agent calls bd show ag-xyz-123 to read issue body
Agent checks dependencies with bd output
Agent closes issue with bd close ag-xyz-123 after completion

Result: Issue lifecycle managed automatically during implementation.

Troubleshooting

Problem	Cause	Solution
bd command not found	bd CLI not installed or not in PATH	Install bd: `brew install bd` or check PATH
"not a git repository" error	bd requires git repo, current dir not initialized	Run `git init` or navigate to git repo root
"beads not initialized" error	.beads/ directory missing	Human runs `bd init --prefix <prefix>` once
Issue ID format errors	Wrong prefix or malformed ID	Check rigs.json for correct prefix, follow `<prefix>-<tag>-<num>` format

beads