Beads (bd)

Distributed, Dolt-backed (Git-like) graph issue tracker for AI coding agents. Persistent memory with dependency-aware task tracking.

Quick Start

Install: brew install steveyegge/beads/bd or use the install script from the GitHub repo.

# Initialize in repo (humans run once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

When to Use

• AI agent needs persistent task memory across sessions
• Tracking dependencies between tasks (blocks:, depends_on:)
• Multi-agent/multi-branch workflows (hash-based IDs prevent conflicts)
• Incremental delivery with molecules/gates
• Sync issues with GitLab, Linear, Jira, GitHub

Essential Commands

Hash-Based IDs

Issues use hash-based IDs like bd-a1b2 to prevent merge conflicts:

bd create "Fix login bug" -p 1
# Created: bd-x7k3

bd show bd-x7k3

Hierarchical IDs

bd-a3f8      (Epic)
bd-a3f8.1    (Task)
bd-a3f8.1.1  (Sub-task)

Use bd children <id> to view hierarchy.

References

Key Concepts

Dolt as Database

Beads stores issues in a Dolt database. Team synchronization happens via Dolt-style pull/push, not by committing JSONL files into your repo history.

Dependency Graph

bd dep add bd-child bd-parent --blocks   # child blocks parent
bd dep add bd-a bd-b --related           # related items
bd ready                                 # only shows unblocked work

Molecules (Advanced)

Molecules group related issues with gates for incremental delivery:

bd mol create "Feature X" --steps=3      # Create 3-step molecule
bd mol progress bd-xyz                   # Check progress
bd mol burn bd-xyz                       # Complete molecule

Stealth Mode

Use Beads locally without committing to repo:

bd init --stealth

Contributor vs Maintainer

# Contributor (forked repos) — separate planning repo
bd init --contributor

# Maintainer auto-detected via SSH/HTTPS credentials

Configuration

Config stored in .beads/config.yaml:

The exact schema evolves between releases. Prefer using CLI helpers to inspect and validate your current setup:

• bd dolt show to see current Dolt connection/remote settings
• bd dolt test to validate connectivity
• bd doctor / bd doctor --deep for health checks

Storage Backend (Dolt)

Beads uses Dolt as its primary backend. Depending on your setup, Dolt can run:

• Embedded (single-writer, no daemon)
• Server mode (multi-writer)

Use bd doctor (and bd doctor --server when applicable) to validate your environment. For legacy stores, use bd migrate workflows.

Agent Integration

Tell Agent About Beads

Add to AGENTS.md:

## Task Tracking

Use `bd` for task tracking. Run `bd ready` to find work.

Agent-Optimized Output

BD_AGENT_MODE=1 bd list --json  # Ultra-compact JSON output
bd list --json                   # Standard JSON output

MCP Plugin

Beads includes Claude Code MCP plugin for direct integration.

Release Highlights (0.60.0)

• GitHub Issues joins the tracker integration surface alongside GitLab, Linear, and Jira.
• bd bootstrap now executes workspace identity and recovery actions directly instead of only printing advice.
• bd context provides a concise working-context surface for the current workspace/session.
• --design-file lets you source design content from files instead of forcing large inline payloads.
• bd init / re-init flows add --destroy-token for safer non-interactive destructive initialization.
• Error handling is more machine-friendly with JSON-aware output and JSONL schema validation.
• If a repo-local PRIME file is missing, Beads can fall back to ~/.config/beads/PRIME.md.

Critical Commands

# What to work on
bd ready                    # Unblocked tasks
bd ready --pretty           # Formatted output

# Create with dependencies
bd create "Task B" --blocks bd-a1b2

# Doctor (fix issues)
bd doctor                   # Check health
bd doctor --fix             # Auto-fix problems

bd sync                     # Sync DB state

bd dolt pull                # Pull latest changes (advanced)
bd dolt push                # Push to remote (advanced)

Anti-patterns

Links

• Releases
• Documentation
• Community Tools