beads/docs/index.md
Chris Sells 8c974d8dc4
docs: align user docs and CLI reference with the v1.1.0 release (#4874)
* docs: align user docs and CLI reference with the v1.1.0 release

The Mintlify site publishes from main, so the docs had drifted ahead of the
latest release — documenting features that no released binary ships.

- Remove architecture/storage-backends: v1.1.0 supports only Dolt (the
  SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the
  old routes to /architecture/dolt and drop the alternate-backend claims
  from README, core-concepts, architecture index, and FAQ.
- Stamp the docs homepage with the release: "These docs are for the 1.1.0
  release" plus a link to the v1.1.0 release notes.
- Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md,
  docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes
  pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim,
  unclaim) and post-1.1.0 flags.
- Fix hand-written pages that referenced post-1.1.0 CLI surface, verified
  against the v1.1.0 binary: bd dep relate/unrelate (not top-level
  relate/unrelate), bd admin reset (not bd reset), bd hooks list (not
  status), bd history / bd vc status (not vc log/diff), release the claim
  via bd assign + bd update (no bd unclaim), drop bd migrate-personal and
  bd daemon mentions, and reduce the Cursor integration page to the rules
  file that v1.1.0's bd setup cursor actually installs.
- Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the
  nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints
  its own operator guidance by design; docs now defer to it.

* docs: auto-regenerate CLI reference

Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-07-17 14:17:28 -07:00

3.1 KiB

title description
Introduction Dependency-aware, Dolt-backed issue tracker built for AI coding agents that survive context loss

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

These docs are for the 1.1.0 release of beads — see the v1.1.0 release notes.

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