Introduction

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

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

Getting Started

Core Concepts

Architecture

Workflows

Recovery

Multi-Agent

Integrations

Community

Reference

Why Beads?

Quick Start

Core Concepts

For AI Agents

Architecture

Next Steps

​Why Beads?

​Quick Start

​Core Concepts

​For AI Agents

​Architecture

​Next Steps

Why Beads?

Quick Start

Core Concepts

For AI Agents

Architecture

Next Steps