Beads CLI (bd)
Task tracking across sessions. All issue tracking goes through bd.
When This Applies
| Signal | Action |
|---|---|
| Need to create a task | bd create |
| Looking for work | bd ready --json |
| Claiming a task | bd update --status in_progress |
| Finishing a task | bd close |
| Managing dependencies | bd dep add/tree |
Core Workflow
bash
# Finding work bd ready --json # Unblocked tasks ready for work bd blocked # Tasks waiting on dependencies bd list # All tasks # Task lifecycle bd create "Title" -t bug -p 1 # Create with type, priority bd update bd-42 --status in_progress --assignee YOUR_NAME # Claim bd close bd-42 --reason "Completed: summary" # Complete # Viewing bd show bd-42 # Full task details bd info # Project summary
Dependencies
bash
bd dep add bd-child bd-blocker --type blocks # Child blocked by blocker bd dep add bd-a bd-b --type related # Related tasks bd dep add bd-child bd-parent --type parent-child # Hierarchy bd dep add bd-new bd-old --type discovered-from # Found during work bd dep tree bd-42 # Visualize dependencies bd dep cycles # Find circular deps
Task Types and Priority
| Type | Use For |
|---|---|
bug | Defects, errors |
feature | New functionality |
task | General work items |
epic | Parent/container beads |
chore | Maintenance, cleanup |
| Priority | Meaning |
|---|---|
0 | Critical (do first) |
1 | High |
2 | Normal |
3 | Low |
4 | Backlog |
Child Beads
Hierarchical IDs: bd-a1b2.1, bd-a1b2.3.1
bash
bd create "Sub-task" --parent bd-123 -p 1
Claiming Protocol (Multi-Agent)
CRITICAL: Always claim parent AND all sub-beads together.
bash
bd update bd-123 --status in_progress --assignee YOUR_NAME bd update bd-123.1 --status in_progress --assignee YOUR_NAME bd update bd-123.2 --status in_progress --assignee YOUR_NAME
Why: If you only claim parent, other agents see sub-beads as "ready" → CONFLICT.
Closing Protocol
CRITICAL: Close sub-beads first, then parent.
bash
bd close bd-123.1 --reason "Completed: implemented X" bd close bd-123.2 --reason "Completed: added tests" bd close bd-123 --reason "Completed: full feature done"
Maintenance
bash
bd doctor # Health check bd doctor --fix # Auto-fix issues bd compact --analyze --json # Analyze for compaction bd --readonly list # Safe read-only mode
Key Rules
| Rule | Why |
|---|---|
Always commit .beads/ with code | Keeps state in sync |
Never edit .beads/*.jsonl directly | Use bd commands only |
Always set --assignee when claiming | Prevents conflicts |
| Never use other TODO systems | Beads is authoritative |
Quick Reference
bash
bd ready --json # What's available? bd update ID --status in_progress --assignee NAME # Claim bd close ID --reason "..." # Complete bd create "Title" -t TYPE -p PRIORITY # Create bd dep add CHILD BLOCKER --type blocks # Add dependency bd doctor --fix # Health check
See Also
- •
beads-viewer/— Graph analysis withbv - •
advance/— Full bead lifecycle (claiming, working, closing)