Beads CLI (bd)

Task tracking across sessions. All issue tracking goes through bd.

When This Applies

Core Workflow

# 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

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

Child Beads

Hierarchical IDs: bd-a1b2.1, bd-a1b2.3.1

bd create "Sub-task" --parent bd-123 -p 1

Claiming Protocol (Multi-Agent)

CRITICAL: Always claim parent AND all sub-beads together.

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.

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

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

Quick Reference

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 with bv
• advance/ — Full bead lifecycle (claiming, working, closing)