About beads
Beads is a graph-based issue tracker for AI agents managing work that spans sessions. Its persistent issue state, dependencies, and Dolt-backed team sync help preserve context through conversation compaction.
Key features
- 01Persistent issue tracking
- 02Dependency-aware work planning
- 03Resume work after compaction
- 04Dolt-backed team synchronization
- 05JSON command output
Use cases
- 01Track a feature across multiple sessions
- 02Find and claim unblocked tasks
- 03Restore in-progress work after compaction
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/beadsin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
CLAUDE.mdadr/0001-bd-prime-as-source-of-truth.mdagents/openai.yamlcommands/audit.mdblocked.mdclose.mdcomments.mdcompact.mdcreate.mddecision.mddelete.mddep.mdepic.mdexport.mdimport.mdinit.mdlabel.mdlist.mdprime.mdquickstart.mdready.mdrename-prefix.mdreopen.mdrestore.mdsearch.mdshow.mdstats.mdsync.mdtemplate.mdupdate.mdDetails
From the project READMEBeads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
bd vs TodoWrite
Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
| bd (persistent) | TodoWrite (ephemeral) |
|---|---|
| Multi-session, dependencies, compaction survival | Single-session linear tasks |
| Dolt-backed team sync | Conversation-scoped |
See BOUNDARIES.md for detailed comparison.
Prerequisites
bd --version # Requires v0.60.0+
- bd CLI installed and in PATH
- Git repository (optional — use
BEADS_DIR+--stealthfor git-free operation) - Initialization:
bd initrun once (humans do this, not agents)
CLI Reference
Run bd prime for AI-optimized workflow context (auto-loaded by hooks).
Run bd <command> --help for specific command usage.
Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push
Session Protocol
bd ready— Find unblocked workbd show <id>— Get full contextbd update <id> --claim— Claim and start work atomically- Add notes as you work (critical for compaction survival)
bd close <id> --reason "..."— Complete taskbd dolt push— Push to Dolt remote (if configured)
Output
Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.
Error Handling
| Error | Fix |
|---|---|
database not found | bd init <prefix> in project root |
not in a git repository | git init first |
disk I/O error (522) | Move .beads/ off cloud-synced filesystem |
| Status updates lag | Use server mode: bd dolt start |
See TROUBLESHOOTING.md for full details.
Examples
Track a multi-session feature:
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json # Shows unblocked work
bd update <id> --claim --json # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json
Recover after compaction: bd list --status in_progress --json then bd show <id> --long
Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json
Advanced Features
| Feature | CLI | Resource |
|---|---|---|
| Molecules (templates) | bd mol --help | MOLECULES.md |
| Chemistry (pour/wisp) | bd pour, bd wisp | CHEMISTRY_PATTERNS.md |
| Agent beads | bd agent --help | AGENTS.md |
| Async gates | bd gate --help | ASYNC_GATES.md |
| Worktrees | bd worktree --help | WORKTREES.md |
Resources
| Category | Files |
|---|---|
| Getting Started | BOUNDARIES.md, CLI_REFERENCE.md (live reference pointers), WORKFLOWS.md |
| Core Concepts | DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md |
| Resilience | RESUMABILITY.md, TROUBLESHOOTING.md |
| Advanced | MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md |
| Reference | STATIC_DATA.md, INTEGRATION_PATTERNS.md |
Validation
If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).