* 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>
3.1 KiB
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 readyshows 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
- Installation - Get bd installed
- Quick Start - Create your first issues
- How Beads Works - The concept model on one page
- CLI Reference - All available commands
- Workflows - Formulas, molecules, and gates