majiayu000 Beads (bd) - Persistent Task Memory
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
When to Use bd vs TodoWrite
| Use bd when... | Use TodoWrite when... |
|---|---|
| Work spans multiple sessions | Single-session tasks |
| Tasks have dependencies/blockers | Simple linear checklist |
| Need context after compaction | All context in current conversation |
| Exploratory/research work | Will complete this session |
Decision rule: If resuming in 2 weeks would be hard without bd, use bd.
Session Start Protocol
bd ready- Find unblocked tasks (sorted by priority)- Pick highest priority (P0 > P1 > P2 > P3 > P4)
bd show <id>- Get full context, dependencies, audit trailbd update <id> --status in_progress- Claim the task- Add notes as you work (critical for compaction survival)
Essential Commands
Find Work
bd ready # Tasks with no blockers
bd list --status=open # All open issues
bd blocked # Show blocked issues
bd show <id> # Full issue details
bd search <query> # Text search
bd stats # Project metrics
Create Issues
bd create "Title" -p <priority> --type <type>
- Priority: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
- Types: task (default), bug, feature, epic, chore
Examples:
bd create "Fix auth bug" -p 0 --type bug
bd create "Add OAuth support" -p 1 --type feature
Update Issues
bd update <id> --status <status> # Change status
bd update <id> --notes "Progress" # Add notes (appends, doesn't replace)
bd update <id> -p 0 # Change priority
Status values: open, in_progress, blocked, closed
Note format (best practice for compaction survival):
COMPLETED: What was done
IN PROGRESS: Current state + next step
BLOCKERS: What's preventing progress
Complete Issues
bd close <id>
bd close <id> -r "Completion summary" # -r optional but recommended
bd close <id1> <id2> # Close multiple
Dependencies
bd dep add <child> <parent> # parent blocks child
bd dep list <id> # View dependencies
Example:
# deploy-task is blocked by test-task
bd dep add deploy-task test-task
Labels
bd label add <id> backend
bd label add <id> security
Git Sync
bd sync # Export, commit, pull, push - all-in-one
Session End Checklist
git status # Check changes
git add <files> # Stage code
bd sync # Sync beads
git commit -m "..." # Commit code
bd sync # Sync any new beads changes
git push # Push to remote
Quick Reference
| Command | Purpose |
|---|---|
bd ready |
Find ready work |
bd create "Title" -p 1 |
Create task |
bd show <id> |
View details |
bd update <id> --status in_progress |
Start work |
bd update <id> --notes "..." |
Add progress |
bd close <id> |
Complete task |
bd dep add <a> <b> |
b blocks a |
bd list |
List all tasks |
bd search <q> |
Find by text |
bd sync |
Git sync |
bd stats |
Project metrics |
Additional Commands
Run bd --help for complete list. Key categories:
- Views & Reports:
activity,count,stale,status - Dependencies & Structure:
epic,graph,duplicate,supersede - Labels & Comments:
label,comments - Maintenance:
repair,doctor,migrate - Integrations:
jira,linear
Error Handling
bd: command not found
Install from https://github.com/steveyegge/beads
No .beads database found
Run bd init (humans do this once, not agents)
Task not found
Use bd list or bd search to find correct ID
Circular dependency detected
Restructure dependencies - bd prevents cycles automatically
Git conflicts in .beads/issues.jsonl
Run bd sync --merge for auto-resolution