| name | beads |
| description | Git-backed 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.
|
| allowed-tools | Read,Bash(bd:*) |
| version | 0.47.1 |
| author | Steve Yegge <https://github.com/steveyegge> |
| license | MIT |
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
| bd (persistent) | TodoWrite (ephemeral) |
|---|
| Multi-session work | Single-session tasks |
| Complex dependencies | Linear execution |
| Survives compaction | Conversation-scoped |
| Git-backed, team sync | Local to session |
Decision test: "Will I need this context in 2 weeks?" → YES = bd
When to use bd:
- Work spans multiple sessions or days
- Tasks have dependencies or blockers
- Need to survive conversation compaction
- Exploratory/research work with fuzzy boundaries
- Collaboration with team (git sync)
When to use TodoWrite:
- Single-session linear tasks
- Simple checklist for immediate work
- All context is in current conversation
- Will complete within current session
Prerequisites
bd --version
- bd CLI installed and in PATH
- Git repository (bd requires git for sync)
- Initialization:
bd init run 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 sync
Session Protocol
bd ready — Find unblocked workbd show <id> — Get full contextbd update <id> --status in_progress — Start work- Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete taskbd sync — Persist to git (always run at session end)
Advanced Features
Resources
Full Documentation
