Agent skill
beads
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.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/guix
SKILL.md
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
bash
bd --version # Requires v0.34.0+
- bd CLI installed and in PATH
- Git repository (bd requires git for sync)
- 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 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
| 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
| Resource | Content |
|---|---|
| BOUNDARIES.md | bd vs TodoWrite detailed comparison |
| CLI_REFERENCE.md | Complete command syntax |
| DEPENDENCIES.md | Dependency system deep dive |
| INTEGRATION_PATTERNS.md | TodoWrite and tool integration |
| ISSUE_CREATION.md | When and how to create issues |
| MOLECULES.md | Proto definitions, component labels |
| PATTERNS.md | Common usage patterns |
| RESUMABILITY.md | Compaction survival guide |
| STATIC_DATA.md | Database schema reference |
| TROUBLESHOOTING.md | Error handling and fixes |
| WORKFLOWS.md | Step-by-step workflow patterns |
| AGENTS.md | Agent bead tracking (v0.40+) |
| ASYNC_GATES.md | Human-in-the-loop gates |
| CHEMISTRY_PATTERNS.md | Mol vs Wisp decision tree |
| WORKTREES.md | Parallel development patterns |
Full Documentation
- bd prime: AI-optimized workflow context
- GitHub: github.com/steveyegge/beads
Didn't find tool you were looking for?