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 beads or use the install scripts/binaries 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 (1.2.2)

• Recovery release: v1.2.0/v1.2.1 were published without release testing; v1.2.2 re-releases the tested 1.1 line under a higher version, so every install channel moves onto tested code. The 1.2.x-only features (work leases, events journal, sync federation, HTTP API server, provenance events) are not in this release — they return in a tested future release.
• If you ran v1.2.1 and hit schema version mismatch: database is at v65, binary knows up to v53: roll the schema cursor back to v53 (see docs/RECOVERY-1.2.1.md), or use the BD_IGNORE_SCHEMA_SKEW=1 stopgap — see references/sync.md. Upgrade every machine/clone to v1.2.2 before recovering, or a leftover 1.2.1 binary will silently re-migrate the database.

Release Highlights (1.1.0)

• Safer migrations: schema-change detection so database migrations no longer apply silently, plus read-only enforcement across all layers.
• Sync repair: repair for previously problematic pull merges, and compaction now archives before discarding information.
• New commands/flags: bd metrics (with a consent notice) and idempotent --init-if-missing initialization.

Release Highlights (1.0.3–1.0.4)

• Workflow/config ergonomics: bd -C changes working directory before running, bd close gains --reason-file, and setup/bootstrap flows gain better remote/server config handling.
• Linear sync: OAuth client-credentials, idempotency markers, stale-data signaling, per-workspace sync locks, richer type mappings, and batch create/update make larger sync loops safer and faster.
• Security/export defaults: Beads now refuses to write secret keys into git-tracked config, and exports exclude memories and ephemeral wisps by default unless you opt back in.
• Dependencies/data paths: JSONL bulk dependency add and several hook/bootstrap/init fixes reduce friction in automated and shared-server environments.

Release Highlights (1.0.0–1.0.2)

• Distribution: precompiled binaries now cover Linux, macOS (Intel/Apple Silicon), Windows (AMD64/ARM64), Android/Termux, and FreeBSD.
• Automation: bd init --non-interactive / --role and bd bootstrap --non-interactive improve CI/cloud-agent setup.
• Workflow: bd ready --explain, bd config set-many, batch dependency listing, and comma-separated status filters improve agent ergonomics.
• Authoring/modeling: spike, story, and milestone are now first-class issue types; custom statuses/types moved to normalized tables.
• Integrations/sync: GitLab sync adds better dedup + epic→milestone mapping, ADO sync respects more filters, and embedded/shared-server recovery got safer.

Release Highlights (0.62.0–0.63.3)

• Azure DevOps integration: bd ado CLI commands (sync, status, projects) for work item tracking.
• Embedded Dolt support: dep, duplicate, epic, graph, supersede, swarm operations work without a running Dolt server.
• Custom status categories: configure active/wip/done/frozen status groupings.
• bd note command: shorthand for appending notes to issues.
• --exclude-type flag: filter by issue type on bd ready and bd list.
• --format json alias: alternative to --json flag for consistency.
• Audit log: captures close reason; status changes logged to interactions.jsonl.
• Memories in export/import: round-trip includes agent memories.
• Init defaults: AGENTS.md defaults to minimal profile; --agents-profile flag added.
• Quality/lifecycle commands: surfaced in prime, template, and doctor.
• Validation on close: --validate checks --acceptance field; validation.on-close config.

Release Highlights (0.61.0)

• bd close --claim-next shortens the common close-and-claim-next loop for agents.
• bd create gains --skills, --context, and --no-history for richer task creation and optional Dolt-history suppression.
• bd import adds incremental JSONL import for portability and recovery workflows.
• bd init / bd bootstrap can auto-detect the Beads database from the repository git origin.
• Dolt/server-mode sync improves credential pass-through, runtime port reporting, and health checks.
• Config and backup handling are safer, including proper project+user config merge and BD_BACKUP_ENABLED=false support.

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
bd create "Task C" --context "Need schema review" --skills "python,sql"

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

bd sync                     # Sync DB state
bd import -i backup.jsonl   # Incremental JSONL import

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

Anti-patterns

Links

• Releases
• Documentation
• Community Tools