beads

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

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  # Requires v0.34.0+

• 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

1. bd ready — Find unblocked work
2. bd show <id> — Get full context
3. bd update <id> --status in_progress — Start work
4. Add notes as you work (critical for compaction survival)
5. bd close <id> --reason "..." — Complete task
6. bd sync — Persist to git (always run at session end)

Advanced Features

Resources

Full Documentation

• bd prime: AI-optimized workflow context
• GitHub: github.com/steveyegge/beads