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

# 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

| 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

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

| 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

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

beads-cli