Beads Issue Tracker
Tracks multi-session work with dependencies and memory across context compaction.
Install
npx skills add gastownhall/beads --skill beads -g -a claude-code -y- Repository
- gastownhall/beads28.4k
- Category
- AI and agents
- Updated
- 3d ago
- License
- MIT
- Context cost
- Lightabout 1,041 tokens
- Runs scripts
- No, instructions only
What it does
Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.
Beads - 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.
