Beads

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.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

Issue Authoring (Spec-Grade Quality)

Write Beads issues that are implementable without guesswork.

Quality Triangle

Every issue must answer:

• What must be true? (description = contract/requirements)
• How do we implement it here? (design = approach + integration map)
• How do we prove it works? (acceptance_criteria = pass/fail)

Minimum Content Bar

Description (Requirements)

Recommended Structure

1. System context: runtime surface, tenant/bot scope, invariants 2. Functional requirements: EARS-style with REQ-### numbering 3. Non-functional requirements: only if measurable 4. Out of scope: explicit non-goals 5. Acceptance scenarios: 3–6 Given/When/Then

EARS Writing Rules

Each requirement must be testable and unambiguous:

• When <trigger>, the system shall <behavior>.
• While <state>, the system shall <behavior>.
• If <condition>, then the system shall <behavior>.

Do not leave behavioral forks (e.g., "reject or return empty — pick one").

Input Contract Checklist

• Field list + types (Pydantic/JSON schema)
• Defaulting rules
• Validation constraints (ranges, max window, enums)
• Time semantics (timezone source, absolute vs relative)
• Tenant scoping fields
• Invalid input behavior and signaling model

Output Contract Checklist

• Field list + types
• Ordering guarantees
• Empty result signaling (empty_reason values)
• Debug block (flag-controlled)
• Error signaling model

Design (Implementation Plan)

Recommended Structure

1. Current state (what exists today) 2. Proposed approach (decisions and rationale) 3. Data flow (bullets or Mermaid diagram) 4. Integration map (files/modules/symbols) 5. Isolation & invariants (RLS, required identifiers) 6. Risks & mitigations

Architecture Decomposition

Make component boundaries explicit:

• API/handler layer
• Tool/agent layer
• Service layer
• Data access layer (RLS enforcement)
• External deps (RAG, cache)

For each component: public interface, failure modes, observability.

File-Backed Design Input (v0.60.0)

When the design section is large or already exists as a checked-in document, prefer passing it from a file instead of stuffing it into inline CLI arguments.

bd create "Implement feature X" --design-file ./docs/feature-x-design.md

This keeps issue creation reproducible and avoids truncation/quoting mistakes in automation.

PRIME.md Fallback

If a repository-local PRIME guidance file is absent, Beads can fall back to ~/.config/beads/PRIME.md.

• Use the global fallback for durable personal authoring defaults.
• Keep repo-specific constraints in the repository when they materially affect implementation or review.

Cutover Checklist (when replacing legacy)

• Tool catalog/registry: remove legacy tool visibility
• Tool exports: ensure legacy not re-exported
• Runtime toolset: ensure legacy not registered
• References: update prompts/docs

Acceptance Criteria

Scenario Template

Scenario A (Happy path)
- Given <precondition>
- When <trigger/input>
- Then <observable outputs>

Scenario B (Empty result)
- Given <no matching data>
- When <trigger/input>
- Then <empty_reason + no hallucination>

Scenario C (Constraints/limits)
- Given <invalid window / out-of-range>
- When <trigger/input>
- Then <exact behavior and signaling>

Multi-Tenant Isolation Scenario (mandatory when applicable)

- Given tenant A and tenant B have different data
- When tenant A invokes the feature
- Then only tenant A data is returned

Require proof in design: where tenant context is derived and set.

NFRs (Non-Functional Requirements)

Only include if measurable. Use prefixes:

• PERF-###: Latency/size budgets
• QUAL-###: Quality targets with measurement method

Example:

• PERF-001: When retrieval is executed, p95 latency shall be < 500ms.
• QUAL-001: Grouping correctness shall achieve 95% measured by manual sampling.

Task Authoring

Decompose each STAGE into 3–8 atomic TASKs:

• Schemas/contract
• Data access (queries, RLS)
• Business logic
• Formatting/output
• Observability
• Tests

Each TASK must name concrete touch points and what verification it adds.

Issue types (v1.0.0)

Beads now treats spike, story, and milestone as first-class issue types.

• Use story for user-visible slices of behavior.
• Use spike for bounded investigation where uncertainty reduction is the deliverable.
• Use milestone for tracking larger delivery checkpoints without forcing an epic/task misuse.
• Newer sync integrations map these built-in types more completely into external trackers such as Linear and GitHub, so prefer the built-in names when external tracker fidelity matters.

Custom statuses and custom types also moved to normalized tables in the 1.0.x line. Prefer built-in types when they fit; use custom types only when the workflow semantics are truly different.

Molecules & Gates

Molecules group related issues for incremental delivery with QA checkpoints.

Concepts

Molecule

A molecule is a collection of related issues (steps) that form a deliverable unit:

bd mol create "Feature X" --steps=3
# Creates: bd-xyz (molecule) with 3 step issues

Gates

Gates are QA checkpoints between steps:

bd ready --gated           # Tasks waiting at gates
bd gate check bd-xyz       # Evaluate gate conditions

Creating Molecules

Simple Molecule

bd mol create "Add user auth" --steps=3

Creates:

• bd-abc (molecule root)
• bd-abc.1 (step 1)
• bd-abc.2 (step 2)
• bd-abc.3 (step 3)

With Variables

bd mol create "Feature" --steps=2 --var="component=auth"

From Formula

bd mol pour my-formula --var="name=auth"

Managing Molecules

# Progress check
bd mol progress bd-abc

# Show last activity timestamp (v0.58.0)
bd mol last-activity bd-abc

# Show compound structure
bd mol show bd-abc

# Complete molecule
bd mol burn bd-abc

# Batch burn
bd mol burn bd-abc bd-def bd-ghi

Wisps (Ephemeral Molecules)

Wisps are ephemeral molecules for operational loops that you _don’t_ want to keep as persistent, shareable history.

Create a wisp from a proto or a formula name:

bd mol wisp mol-patrol
bd mol wisp beads-release --var version=1.0

Manage existing wisps:

bd mol wisp list
bd mol wisp gc

Notes:

• In newer versions, wisp creation defaults to a root-only workflow unless the

formula explicitly opts into pouring child steps. Use --root-only when you want to force creating only the root issue.

Wisp lifecycle shortcuts:

• Promote a wisp to persistent work: bd mol squash <id>
• Delete a wisp without preserving it: bd mol burn <id>

Gate Types

Human Gates

Manual approval required:

bd gate add-waiter bd-step1 --human
bd gate show bd-step1

Timer Gates

Wait for time period:

bd gate check bd-xyz  # Checks timer conditions

GitHub Gates

Wait for CI/workflow:

bd gate check bd-xyz --gh:run  # Check GitHub Actions
bd gate discover bd-xyz        # Auto-discover workflow ID

Merge-Slot Gates

Serialized conflict resolution:

bd slot set bd-xyz agent-1
bd slot show bd-xyz

Formulas

Reusable molecule templates:

# List formulas
bd formula list

# Pour (instantiate) formula
bd mol pour release-checklist --var="version=1.0"

# Validate template
bd lint template.yaml

Formula Structure

name: release-checklist
steps:
  - title: "Prepare {{version}}"
    gate:
      type: human
  - title: "Deploy {{version}}"
    condition: "{{ci_passed}}"

Compounds

Nested molecule structures:

bd mol show bd-abc --tree  # Show compound hierarchy

Best Practices

1. Use gates for mandatory review points 2. Keep molecules small (3-5 steps max) 3. Name descriptively for audit trail 4. Use formulas for repeatable patterns 5. Check progress regularly with bd mol progress

Sync & Integration

Beads v0.58.0 uses Dolt as the primary backend and supports multiple sync strategies.

TL;DR

• Prefer bd sync for the “do the right thing” sync loop.
• Use bd dolt push / bd dolt pull when operating directly with Dolt remotes.
• Use JSONL export/import for portability, migration, and off-machine backups.

Recommended Loop (Most Teams)

bd sync

At a high level, bd sync:

1. Ensures local DB state is consistent 2. Pulls updates from the configured sync channel 3. Applies merges/conflict strategy 4. Pushes if configured (or if you didn’t opt out)

If you need to skip pushing (e.g. read-only environments):

bd sync --no-push

Init / Bootstrap Auto-Detection (v0.61.0)

bd init and bd bootstrap can now auto-detect the Beads database from the repository's git origin.

• Prefer this when reconnecting an existing clone or repairing a miswired workspace.
• It reduces manual remote/database discovery during bootstrap and recovery flows.

1.0.x adds non-interactive init/bootstrap flows for CI and improves bootstrap recovery in fresh clones and shared-server scenarios.

The 1.0.4 line also adds a more direct remote bootstrap path (bd init --remote) plus cleaner external-server directory override behavior, which is useful when the Beads store is not colocated with the working tree.

Sync Modes

Beads supports different sync modes depending on your backend and workflow. The exact knobs live in .beads/config.yaml / ~/.config/bd/config.yaml.

• dolt-native (recommended): Dolt remotes handle sync; cell-level merge.
• git-portable (legacy portability): JSONL export/import during sync operations.
• belt-and-suspenders: Dolt remotes + JSONL backups for extra redundancy.

Dolt Remotes

Use bd dolt remote commands to manage remotes without editing config files:

bd dolt remote list
bd dolt remote add origin <url>
bd dolt remote remove origin

bd dolt pull
bd dolt push

Notes:

• For git-protocol remotes, Beads may fall back to the Dolt CLI for transfer.
• bd dolt show and bd dolt test help validate configuration and connectivity.
• In server mode and federation flows, Beads now routes CLI credentials through push/pull/fetch operations more consistently.
• bd context now reports the actual runtime Dolt port instead of assuming the default port.
• Credentials-file support is also available for Dolt server passwords in newer 1.0.x setups.

Multiple Clones / Worktrees: .beads/redirect

To make multiple clones share one database, create .beads/redirect containing a single relative or absolute path to the target .beads directory.

mkdir -p .beads
echo "../main-clone/.beads" > .beads/redirect

bd where
bd where --json

Constraints:

• Redirects are single-level (A → B works; A → B → C does not)
• Target must exist and contain a valid database

Backup / Portability (JSONL)

Use JSONL as an off-machine recovery path and migration/portability tool.

bd export -o backup.jsonl
bd import -i backup.jsonl

If auto-backup is enabled, you can trigger it manually:

bd backup
bd backup status

Set BD_BACKUP_ENABLED=false when automation must suppress backup commits.

Recent export defaults changed in a safer direction:

• bd export excludes memories by default.
• bd export excludes ephemeral wisps by default.

If you rely on older "everything goes into export" assumptions for migration or audit tooling, re-test those flows and opt back in intentionally where needed.

Upgrades & Migrations

For upgrades, prefer inspecting first:

bd migrate --inspect --json
bd migrate --to-dolt --dry-run
bd migrate --to-dolt

Recent releases also merge user-level config under project config instead of discarding it.

External Integrations

Integrations (GitLab/Linear/Jira/etc.) are separate from database sync: sync keeps Beads’ local issue database consistent; integrations exchange data with external trackers.

For automation, prefer structured/JSON-aware error handling when integration commands fail instead of scraping human-readable error text.

1.0.x also tightened integration safety: external tracker content is sanitized for terminal display, response sizes are bounded, and sync warnings are surfaced more explicitly.

bd doctor also has stronger server-mode behavior, including cold-start Dolt detection and committed runtime/sensitive-file detection.

Recent config safety tightened further: secret keys are refused in git-tracked config.yaml, so treat secrets as out-of-repo state instead of assuming the CLI will happily persist them into tracked config.

GitLab Sync

bd gitlab sync
bd gitlab status

Recent updates improved GitLab dedup behavior, type filtering, and epic → milestone mapping.

GitHub Issues Sync (v0.60.0)

bd github sync
bd github status

Use this when your coordination loop lives in GitHub Issues instead of GitLab, Linear, or Jira.

Linear Sync

bd linear sync --project-id=<id>

Recent 1.0.4 Linear upgrades matter operationally:

• OAuth client-credentials support for headless/service setups
• Ambient staleness signaling for auto-fresh data
• Idempotency markers to prevent duplicate issue creation
• Per-workspace concurrency locks on sync
• Batch create/update flows for much faster bulk sync
• Type mappings for decision, spike, story, and milestone

Jira Import

bd jira import --project=KEY

Azure DevOps sync notes (1.0.x)

• ADO push flows now respect --types, --states, and --no-create filters more consistently.
• New work items are created in the initial state and then transitioned to the target state when needed.

Daily Workflow

Daily task operations with bd CLI.

Non-interactive setup (v1.0.0)

Use the non-interactive flags when bootstrapping CI runners or cloud agents that cannot answer prompts.

bd init --non-interactive --role=<role>
bd bootstrap --non-interactive

Use --role to make the workspace intent explicit for agent automation.

Recent 1.0.4 setup/workflow additions:

• bd init --remote helps bootstrap against a remote-backed setup path more directly.
• bd -C <dir> ... changes directory before command execution, which is useful in automation that orchestrates multiple repos/workspaces from one parent shell.

Daily Loop

# 0. Sync database state
bd sync

# 0b. Repair bootstrap/identity state when a workspace looks miswired
bd bootstrap

# 1. What can I work on?
bd ready                    # Unblocked tasks
bd ready --pretty           # Formatted output
bd ready --gated            # Tasks at gate checkpoints

# (Optional) see what is currently active
bd show --current

# 2. Pick and start work
bd update bd-xyz --status=in_progress

# 3. Complete work
bd close bd-xyz --reason "Implemented per spec"
bd close bd-xyz --reason "Implemented per spec" --claim-next

# 4. Share DB changes (when you want to share)
bd sync

If you are operating directly against Dolt remotes (advanced), you can also use:

bd dolt pull
bd dolt push

Finding Work

Workspace Context

bd context
bd context --json

Use this before planning or handoff when you need a concise snapshot of the current workspace/task state.

Ready Tasks

bd ready                    # Tasks with no open blockers
bd ready --explain          # Explain dependency/blocker reasoning
bd ready --json             # JSON output for agents
bd ready --limit=10         # Limit results

List Tasks

bd list                     # Default: 50 non-closed issues
bd list --all               # All issues
bd list --status=open       # Filter by status
bd list --status=open,in_progress  # Comma-separated status values
bd list --type=bug          # Filter by type
bd list --tree              # Tree view with hierarchy
bd list --tree --parent=bd-abc  # Subtree

Show Details

bd show bd-xyz              # Full details + audit trail
bd show bd-xyz --short      # Compact output
bd view bd-xyz              # Alias for show
bd show --id bd-xyz         # Use when ID could be parsed as a flag

Status Updates

# Update status
bd update bd-xyz --status=in_progress
bd update bd-xyz --status=done

# Update with fields
bd update bd-xyz --priority=0 --assignee="agent-1"

# Batch update
bd update bd-abc bd-def --status=in_progress

# Append notes
bd update bd-xyz --append-notes "New info"

# Ephemeral / persistent markers
bd update bd-xyz --ephemeral
bd update bd-xyz --persistent

Status Values

Closing Tasks

# Close with reason (recommended)
bd close bd-xyz --reason "Implemented and tested"

# Close with a longer reason from file
bd close bd-xyz --reason-file ./close-reason.md

# Close and immediately claim the next ready task
bd close bd-xyz --reason "Implemented and tested" --claim-next

# Close multiple
bd close bd-abc bd-def --reason "Batch completion"

# Cannot close if blockers exist
# bd close bd-blocked  # Error: has open blockers

Dependencies

# Add dependency (child blocks parent)
bd dep add bd-child bd-parent --blocks

# Add related link
bd dep add bd-a bd-b --related

# Remove dependency
bd dep rm bd-child bd-parent

# View dependency tree
bd dep tree bd-xyz

1.0.x also adds batch dependency listing for multiple issue IDs, which is useful when an agent is triaging several candidates at once.

Recent 1.0.4 automation paths also add JSONL bulk dependency add, which is useful when importing or repairing a larger dependency graph from generated/project data instead of issuing one bd dep add per edge.

Labels

# Add labels
bd label add bd-xyz urgent backend

# Remove labels
bd label remove bd-xyz urgent

# List by label
bd list --label=urgent

Activity Feed

bd activity                 # Recent activity
bd activity --watch         # Real-time feed
bd activity --town          # Cross-rig aggregated feed
bd activity --details       # Full issue details

Agent Mode

For AI agents, use structured output:

BD_AGENT_MODE=1 bd ready --json
BD_AGENT_MODE=1 bd list --json

Key-Value Store

Store arbitrary key-value data alongside issues:

bd kv set config.api_url "https://api.example.com"
bd kv get config.api_url
bd kv list                  # List all keys
bd kv delete config.api_url

Useful for storing agent configuration, session state, or project metadata.

Batch config updates (v1.0.0)

Use bd config set-many when automation needs to apply several config changes together instead of mutating keys one by one.

Backend Management

bd dolt show                # Show Dolt connection/remote settings
bd dolt test                # Validate connectivity

Backup & Restore

Beads can produce JSONL backups for off-machine recovery and portability.

bd backup
bd backup status

bd export -o backup.jsonl
bd import -i backup.jsonl

Notes:

• Use bd backup --help to see the available options (location, format, automation).
• Treat restore as a bootstrap/recovery tool; validate Dolt connectivity after restoring.
• bd import supports incremental JSONL replay workflows and avoids duplicating already-imported comment history.

Richer Task Creation (v0.61.0)

bd create "Task C" --context "Needs schema review" --skills "python,sql"
bd create "Scratch task" --no-history

• --context captures concise execution context at creation time.
• --skills records the intended skill/tooling surface for the task.
• --no-history skips the Dolt commit for that create operation without making the item GC-eligible.

Maintenance

Standalone lifecycle helpers for keeping the Beads store healthy:

bd gc
bd compact
bd flatten

Purge Closed Ephemeral Beads (v0.58.0)

Delete closed ephemeral beads (wisps) to reclaim storage:

bd purge

Persistent Agent Memory (v0.58.0)

For knowledge that should survive sessions:

bd remember "key" "value"
bd memories
bd recall "key"
bd forget "key"

Claiming Work

bd update bd-xyz --claim    # Mark as claimed by current agent

Session End

# Sync before ending session (when you want to share)
bd sync

Export

bd export -o backup.jsonl     # Export full DB backup (JSONL)
bd export --id bd-xyz        # Export specific issue
bd export --parent bd-abc    # Export subtree by parent

Troubleshooting

bd doctor                   # Health check
bd doctor --fix             # Auto-fix issues
bd doctor --deep            # Full integrity check
bd doctor --server          # Dolt server mode health checks
bd doctor --agent           # Diagnostics for AI agent setups (v0.57.0)

Safe Re-initialization (v0.60.0)

When automation must reinitialize a store non-interactively, use the explicit destroy-token flow instead of scripting blind destructive prompts.

bd init --destroy-token <token>

Treat the token as a deliberate safety barrier, not as a convenience flag to hardcode into generic scripts.