beads/docs/index.md
Chris Sells 1ea7ea2a99 docs: fix phantom command surfaces in workflow pages
The ported workflow pages documented commands that do not exist in bd:
bd pour, bd wisp create/list/show/delete/cleanup, bd pin, bd hook, and a
.beads-wisp/ storage directory. Verified against the live binary: the
real surface is bd cook, bd mol pour, bd mol wisp (+ list/gc), bd mol
squash/burn, bd create --ephemeral, and bd purge; wisps are rows in the
main database with Ephemeral=true, excluded from federation push by
default, not a separate gitignored store.

Rewrote workflows/wisps.md around the verified lifecycle
(create -> execute -> squash or burn), fixed formulas.md instantiation
examples, dropped the design-doc status header from adaptive-ids, and
linked the home page's concept table to the canonical pages.
2026-07-12 10:37:07 -07:00

2.9 KiB

title
Introduction

Beads (bd) is a Dolt-powered issue tracker designed for AI-supervised coding workflows.

Why Beads?

Traditional issue trackers (Jira, GitHub Issues) weren't designed for AI agents. Beads was built from the ground up for:

  • AI-native workflows - Hash-based IDs prevent collisions when multiple agents work concurrently
  • Dolt-backed storage - Issues stored in a version-controlled SQL database, enabling collaboration via Dolt-native replication
  • Dependency-aware execution - bd ready shows only unblocked work
  • Formula system - Declarative templates for repeatable workflows
  • Multi-agent coordination - Routing, gates, and molecules for complex workflows

Quick Start

# Install via Homebrew (macOS/Linux)
brew install beads

# Or quick install (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in your project
cd your-project
bd init --quiet

# Create your first issue
bd create "Set up database" -p 1 -t task

# See ready work
bd ready

Core Concepts

The whole model on one page: How Beads Works.

Concept Description
Beads (issues) Work items with priorities, types, labels, and dependencies
Dependencies blocks, parent-child, discovered-from, related
Sync Dolt push/pull over your git remote — no server to run
Formulas Declarative workflow templates (TOML or JSON)
Molecules Work graphs instantiated from formulas
Gates Async coordination primitives (human, timer, GitHub)

For AI Agents

Beads is optimized for AI coding agents:

# Always use --json for programmatic access
bd list --json
bd show bd-42 --json

# Track discovered work during implementation
bd create "Found bug in auth" --description="Details..." \
  --deps discovered-from:bd-100 --json

# Push changes at end of session
bd dolt push

See the Claude Code integration for detailed agent instructions.

Architecture

Dolt DB (.beads/embeddeddolt/ in embedded mode,
         .beads/dolt/ in server mode; gitignored)
    ↕ dolt commit
Local Dolt history
    ↕ dolt push/pull
Remote Dolt repository (shared across machines)

The magic is automatic synchronization via Dolt's version-controlled database with built-in replication.

Next Steps