Beads

Distributed, git-backed graph issue tracker for AI agents. Replaces markdown plans with a dependency-aware task graph stored as JSONL in .beads/.

Quick Start

# Initialize (non-interactive for agents)
bd init --quiet

# Check ready work
bd ready --json

# Create a task
bd create "Complete task X" -p 1 --json

# View task
bd show bd-a1b2 --json

Core Workflow

1. bd ready --json — Find unblocked work
2. bd update <id> --status in_progress — Claim task
3. Do the work
4. bd close <id> --reason "Done" — Complete task
5. bd sync — Force sync before ending session

Agent-Critical Rules

• Always use --json for machine-readable output
• Never use bd edit — opens $EDITOR, unusable by agents
• Use bd update instead: bd update <id> --title "New title" --description "New desc"
• Run bd sync at end of session to flush changes to git

Commands

Initialize

bd init --quiet              # Non-interactive, auto-installs hooks
bd init --prefix myproj      # Custom ID prefix
bd init --stealth            # Local only, don't commit .beads/
bd init --contributor        # Fork workflow (separate planning repo)

Create Issues

bd create "Title" -p 1 --json                    # Priority 1 (0=critical, 3=low)
bd create "Title" -t epic -p 0 --json            # Create epic
bd create "Subtask" -p 1 --json                  # Under epic: bd-a3f8.1, .2, .3
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Types: task, bug, feature, epic Priorities: 0 (P0/critical) to 3 (P3/low)

Query Issues

bd ready --json                    # Unblocked tasks (the work queue)
bd ready --priority 0 --json       # Only P0s
bd ready --assignee agent-1 --json # Assigned to specific agent

bd list --json                     # All issues
bd list --status open --json       # Open issues
bd list --priority 1 --json        # P1 issues

bd show bd-a1b2 --json             # Issue details + audit trail
bd blocked --json                  # Issues waiting on dependencies
bd stats --json                    # Statistics

Update Issues

bd update bd-a1b2 --status in_progress --json
bd update bd-a1b2 --title "New title" --json
bd update bd-a1b2 --description "Details" --json
bd update bd-a1b2 --priority 0 --json
bd update bd-a1b2 --assignee agent-1 --json
bd update bd-a1b2 --design "Design notes" --json
bd update bd-a1b2 --notes "Additional notes" --json

Status values: open, in_progress, blocked, closed

Close Issues

bd close bd-a1b2 --reason "Completed" --json
bd close bd-a1b2 bd-b2c3 --reason "Batch close" --json

Dependencies

bd dep add bd-child bd-parent      # child blocked by parent
bd dep add bd-a1b2 bd-b2c3 --type related    # Related link
bd dep add bd-a1b2 bd-epic --type parent     # Parent-child

bd dep tree bd-a1b2                # Visualize dependency tree
bd dep remove bd-child bd-parent   # Remove dependency
bd dep cycles                      # Detect circular deps

Dependency types: blocks (default), related, parent, discovered-from

Git Sync

bd sync                    # Export → commit → pull → import → push
bd hooks install           # Install git hooks for auto-sync

The daemon auto-syncs with 30s debounce. Use bd sync to force immediate sync.

Maintenance

bd admin compact --dry-run --json   # Preview compaction
bd admin compact --days 90          # Compact issues closed >90 days
bd doctor                           # Check database health

Hierarchical IDs (Epics)

bd create "Project Alpha" -t epic -p 1 --json   # Returns: bd-a3f8
bd create "Phase 1" -p 1 --json                 # Returns: bd-a3f8.1
bd create "Research" -p 1 --json                # Returns: bd-a3f8.2
bd create "Review" -p 1 --json                  # Returns: bd-a3f8.3

Up to 3 levels: bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1

Multi-Agent Coordination

# Agent claims work
bd update bd-a1b2 --status in_progress --assignee agent-1 --json

# Query assigned work
bd ready --assignee agent-1 --json

# Track discovered work
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Commit Convention (Optional)

For git-tracked projects, include issue ID in commit messages for traceability:

git commit -m "Complete research phase (bd-a1b2)"

Session End Checklist

Before ending a session:

bd sync                    # Flush all changes
bd ready --json            # Show next work for handoff