beads/website/static/llms-full.txt
Ben Madore 3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00

6275 lines
122 KiB
Text

# Beads Documentation (Complete)
> This file contains the complete beads documentation for LLM consumption.
> Generated automatically from the documentation source files (version: 1.0.0).
> For the web version, visit: https://gastownhall.github.io/beads/
---
<document path="docs/intro.md">
# Beads Documentation
**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
```bash
# 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
| Concept | Description |
|---------|-------------|
| **Issues** | Work items with priorities, types, labels, and dependencies |
| **Dependencies** | `blocks`, `parent-child`, `discovered-from`, `related` |
| **Dolt Server** | Database server for multi-writer access and performance |
| **Formulas** | Declarative workflow templates (TOML or JSON) |
| **Molecules** | Work graphs with parent-child relationships |
| **Gates** | Async coordination primitives (human, timer, GitHub) |
## For AI Agents
Beads is optimized for AI coding agents:
```bash
# 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](/integrations/claude-code) for detailed agent instructions.
## Architecture
```
Dolt DB (.beads/dolt/, 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](/getting-started/installation) - Get bd installed
- [Quick Start](/getting-started/quickstart) - Create your first issues
- [CLI Reference](/cli-reference) - All available commands
- [Workflows](/workflows) - Formulas, molecules, and gates
</document>
<document path="docs/getting-started/ide-setup.md">
# IDE Setup for AI Agents
Configure your IDE for optimal beads integration.
## Claude Code
The recommended approach for Claude Code:
```bash
# Setup Claude Code integration
bd setup claude
```
This installs:
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
- **PreCompact hook** - Ensures `bd dolt push` before context compaction
**How it works:**
1. SessionStart hook runs `bd prime` automatically
2. `bd prime` injects ~1-2k tokens of workflow context
3. You use `bd` CLI commands directly
4. Git hooks auto-sync the database
**Verify installation:**
```bash
bd setup claude --check
```
### Manual Setup
If you prefer manual configuration, add to your Claude Code hooks:
```json
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd dolt push"]
}
}
```
## Cursor IDE
```bash
# Setup Cursor integration
bd setup cursor
```
This creates `.cursor/rules/beads.mdc` with beads-aware rules.
**Verify:**
```bash
bd setup cursor --check
```
## Aider
```bash
# Setup Aider integration
bd setup aider
```
This creates/updates `.aider.conf.yml` with beads context.
**Verify:**
```bash
bd setup aider --check
```
## GitHub Copilot
For VS Code with GitHub Copilot, use the MCP server:
```bash
# Install MCP server
uv tool install beads-mcp
```
Create `.vscode/mcp.json` in your project:
```json
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**For all projects:** Add to VS Code user-level MCP config:
| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |
```json
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
```
Initialize beads and reload VS Code:
```bash
bd init --quiet
```
See [GitHub Copilot Integration](/integrations/github-copilot) for detailed setup.
## Context Injection with `bd prime`
All integrations use `bd prime` to inject context:
```bash
bd prime
```
This outputs a compact (~1-2k tokens) workflow reference including:
- Available commands
- Current project status
- Workflow patterns
- Best practices
**Why context efficiency matters:**
- Compute cost scales with tokens
- Latency increases with context size
- Models attend better to smaller, focused contexts
## MCP Server (Alternative)
For MCP-only environments (Claude Desktop, no shell access):
```bash
# Install MCP server
pip install beads-mcp
```
Add to Claude Desktop config:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**Trade-offs:**
- Works in MCP-only environments
- Higher context overhead (10-50k tokens for tool schemas)
- Additional latency from MCP protocol
See [MCP Server](/integrations/mcp-server) for detailed configuration.
## Git Hooks
Ensure git hooks are installed for auto-sync:
```bash
bd hooks install
```
This installs:
- **pre-commit** - Validates changes before commit
- **post-merge** - Imports changes after pull
- **pre-push** - Ensures sync before push
**Check hook status:**
```bash
bd info # Shows warnings if hooks are outdated
```
## Verifying Your Setup
Run a complete health check:
```bash
# Check version
bd version
# Check project health
bd doctor
# Check hooks
bd hooks status
# Check editor integration
bd setup claude --check # or cursor, aider
```
</document>
<document path="docs/getting-started/installation.md">
# Installing bd
Complete installation guide for all platforms.
## Quick Install (Recommended)
### Homebrew (macOS/Linux)
```bash
brew install beads
```
**Why Homebrew?**
- Simple one-command install
- Automatic updates via `brew upgrade`
- No need to install Go
- Handles PATH setup automatically
### Quick Install Script (All Platforms)
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
The installer will:
- Detect your platform (macOS/Linux/FreeBSD, amd64/arm64)
- Install via `go install` if Go is available
- Fall back to building from source if needed
- Guide you through PATH setup if necessary
## Build Dependencies (go install / from source)
If you install via `go install` or build from source, you need system dependencies for CGO:
macOS (Homebrew):
```bash
brew install icu4c zstd
```
Linux (Debian/Ubuntu):
```bash
sudo apt-get install -y libicu-dev libzstd-dev
```
Linux (Fedora/RHEL):
```bash
sudo dnf install -y libicu-devel libzstd-devel
```
If you see `unicode/uregex.h` missing on macOS, `icu4c` is keg-only. Use:
```bash
ICU_PREFIX="$(brew --prefix icu4c)"
CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest
```
## Platform-Specific Installation
### macOS
**Via Homebrew** (recommended):
```bash
brew install beads
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
**From source**:
```bash
git clone https://github.com/gastownhall/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
### Linux
**Via Homebrew** (works on Linux too):
```bash
brew install beads
```
**Arch Linux** (AUR):
```bash
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### FreeBSD
**Via quick install script**:
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### Windows 11
Beads ships with native Windows support—no MSYS or MinGW required.
**Prerequisites:**
- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`)
- Git for Windows
**Via PowerShell script**:
```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```
The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source.
**Via go install**:
```pwsh
go install github.com/steveyegge/beads/cmd/bd@latest
```
If you see `unicode/uregex.h` missing while building, use the PowerShell install script instead.
## IDE and Editor Integrations
### CLI + Hooks (Recommended)
The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:
```bash
# 1. Install bd CLI (see Quick Install above)
brew install beads
# 2. Initialize in your project
cd your-project
bd init --quiet
# 3. Setup editor integration (choose one)
bd setup claude # Claude Code - installs SessionStart/PreCompact hooks
bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider # Aider - creates .aider.conf.yml
```
**How it works:**
- Editor hooks/rules inject `bd prime` automatically on session start
- `bd prime` provides ~1-2k tokens of workflow context
- You use `bd` CLI commands directly
- Git hooks (installed by `bd init`) auto-sync the database
**Why this is recommended:**
- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas
- **Lower latency** - Direct CLI calls, no MCP protocol overhead
- **Universal** - Works with any editor that has shell access
### MCP Server (Alternative)
Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell):
```bash
# Using uv (recommended)
uv tool install beads-mcp
# Or using pip
pip install beads-mcp
```
**Configuration for Claude Desktop** (macOS):
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
## Verifying Installation
After installing, verify bd is working:
```bash
bd version
bd help
```
## Troubleshooting
### `bd: command not found`
bd is not in your PATH:
```bash
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"
```
### `zsh: killed bd` or crashes on macOS
This is typically caused by CGO/SQLite compatibility issues:
```bash
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```
## Updating bd
### Quick install script (macOS/Linux/FreeBSD)
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
### PowerShell installer (Windows)
```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```
### Homebrew
```bash
brew upgrade beads
```
### go install
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading).
## Next Steps
After installation:
1. **Initialize a project**: `cd your-project && bd init`
2. **Learn the basics**: See [Quick Start](/getting-started/quickstart)
3. **Configure your agent**: See [IDE Setup](/getting-started/ide-setup)
</document>
<document path="docs/getting-started/quickstart.md">
# Beads Quick Start
Get up and running with Beads in a few minutes.
## Why Beads?
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:
**Flat tracker (GitHub Issues):**
```
Open issues: Set up database, Create API, Add authentication
→ An agent picks "Add authentication" and gets stuck immediately
```
**Beads:**
```bash
$ bd ready
1. [P1] [task] bd-1: Set up database
$ bd ready --explain --json | jq '.blocked[0]'
{
"id": "bd-3",
"title": "Add authentication",
"blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}
```
The agent picks the right task every time. No wasted cycles.
## Installation
Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).
**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.
```bash
bd --help
```
## Initialize
First time in a repository:
```bash
# Basic setup (prompts for contributor mode)
bd init
# For AI agents (non-interactive)
bd init --quiet
# OSS contributor (fork workflow with separate planning repo)
bd init --contributor
# Team member (branch workflow for collaboration)
bd init --team
# Protected main branch (GitHub/GitLab)
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
```
The wizard will:
- Create `.beads/` directory and embedded Dolt database
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
- Import existing issues from git (if any)
- Prompt to install git hooks (recommended)
- Prompt to configure git merge driver (recommended)
Notes:
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
- To import issues from an older installation, run `bd init --from-jsonl`.
### Role configuration
During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"
- Answer **Y** if you're contributing to a fork (runs contributor wizard)
- Answer **N** if you're the maintainer or have push access
This sets `git config beads.role` which determines how beads routes issues:
| Role | Use case | Issue storage |
|------|----------|---------------|
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
You can also configure manually:
```bash
# Set as contributor
git config beads.role contributor
# Set as maintainer
git config beads.role maintainer
# Check current role
git config --get beads.role
```
**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.
## Your first issues
```bash
# Create a few issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
# List them
bd list
```
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
## Hierarchical issues (epics)
For large features, use hierarchical IDs to organize work:
```bash
# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create child tasks (use --parent to attach to the epic)
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
# View hierarchy
bd dep tree bd-a3f8e9
```
Output:
```
Dependency tree for bd-a3f8e9:
> bd-a3f8e9: Auth System [epic] [P1] (open)
> bd-a3f8e9.1: Design login UI [P1] (open)
> bd-a3f8e9.2: Backend validation [P1] (open)
> bd-a3f8e9.3: Integration tests [P1] (open)
```
## Add dependencies
```bash
# API depends on database
bd dep add bd-2 bd-1
# Auth depends on API
bd dep add bd-3 bd-2
# View the tree
bd dep tree bd-3
```
Output:
```
Dependency tree for bd-3:
> bd-3: Add authentication [P2] (open)
> bd-2: Create API [P2] (open)
> bd-1: Set up database [P1] (open)
```
**Dependency visibility:** `bd list` shows blocking dependencies inline:
```
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
```
## Find ready work
```bash
bd ready
```
Output:
```
Ready work (1 issues with no blockers):
1. [P1] bd-1: Set up database
```
Only bd-1 is ready because bd-2 and bd-3 are blocked.
**Understanding why:** Use `--explain` to see the full graph reasoning:
```bash
bd ready --explain
```
Output:
```
Ready Work Explanation
● Ready (1 issues):
bd-1 [P1] Set up database
Reason: no blocking dependencies
Unblocks: 1 issue(s)
● Blocked (2 issues):
bd-2 [P2] Create API
← blocked by bd-1: Set up database [open]
bd-3 [P2] Add authentication
← blocked by bd-2: Create API [open]
─ Summary: 1 ready, 2 blocked
```
**Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work.
## Work the queue
```bash
# Start working on bd-1
bd update bd-1 --claim
# Complete it
bd close bd-1 --reason "Database setup complete"
# Check ready work again
bd ready
```
Now bd-2 is ready.
## Track progress
```bash
# See blocked issues
bd blocked
# View statistics
bd stats
```
## Team sync
Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs.
```bash
# Add a remote (GitHub example — also supports DoltHub, S3, GCS, local paths)
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
# Push your issues
bd dolt push
# Pull teammates' changes
bd dolt pull
```
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data` and clones it — no manual remote setup needed.
See [Sync](/cli-reference/sync) for CLI details. For remote configuration and federation, see the repository docs [DOLT-BACKEND.md](https://github.com/gastownhall/beads/blob/main/docs/DOLT-BACKEND.md) and [FEDERATION-SETUP.md](https://github.com/gastownhall/beads/blob/main/FEDERATION-SETUP.md).
## Optional: Notion sync
If you keep project issues in Notion, save an integration token first:
```bash
bd config set notion.token <your-token>
```
Then either create a new Beads database under a parent page or connect to an existing target:
```bash
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
```
The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
Check which auth source is active and whether the target schema is ready:
```bash
bd notion status
bd notion status --json
```
Preview or run sync:
```bash
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
```
## Database location
By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
In server mode, data is managed by the external `dolt sql-server`.
## Migrating databases
After upgrading bd, use `bd migrate` to check for and migrate old database files:
```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Check schema and config
bd info --schema --json
# Preview migration changes
bd migrate --dry-run
# Migrate old databases to beads.db
bd migrate
# Migrate and clean up old files
bd migrate --cleanup --yes
```
**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
## Database maintenance
As your project accumulates closed issues, the database grows. Manage size with these commands:
```bash
# View compaction statistics
bd admin compact --stats
# Preview compaction candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediately delete closed issues (CAUTION: permanent!)
bd admin cleanup --force
```
**When to compact:**
- Database file > 10MB with many old closed issues
- After major project milestones when old issues are no longer relevant
- Before archiving a project phase
**Note:** Compaction is permanent graceful decay. Original content is discarded but viewable via `bd restore <id>` from git history.
## Next steps
- Add labels: `bd create "Task" -l "backend,urgent"`
- Filter ready work: `bd ready --priority 1`
- Explain the graph: `bd ready --explain`
- Check graph integrity: `bd graph check`
- Search issues: `bd list --status open`
- Detect cycles: `bd dep cycles`
- Gates for PR/CI sync: [Dependencies](/cli-reference/dependencies)
- More sync scenarios: [Sync](/cli-reference/sync)
- Full command list: [CLI Reference](/cli-reference)
See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.
</document>
<document path="docs/getting-started/upgrading.md">
# Upgrading bd
How to upgrade bd and keep your projects in sync.
## Checking for Updates
```bash
# Current version
bd version
# What's new in recent versions
bd info --whats-new
bd info --whats-new --json # Machine-readable
```
## Upgrading
Use the command that matches your install method.
| Install method | Platforms | Command |
|---|---|---|
| Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` |
| PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` |
| Homebrew | macOS, Linux | `brew upgrade beads` |
| go install | macOS, Linux, FreeBSD, Windows | `go install github.com/steveyegge/beads/cmd/bd@latest` |
| npm | macOS, Linux, Windows | `npm update -g @beads/bd` |
| bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` |
| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && go build -o bd ./cmd/bd` |
### Quick install script (macOS/Linux/FreeBSD)
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
### PowerShell installer (Windows)
```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```
### Homebrew
```bash
brew upgrade beads
```
### go install
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```
### From Source
```bash
cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```
## After Upgrading
**Important:** After upgrading, update your hooks:
```bash
# 1. Check what changed
bd info --whats-new
# 2. Update git hooks to match new version
bd hooks install
# 3. Check for any outdated hooks
bd info # Shows warnings if hooks are outdated
# 4. If using Dolt backend, restart the server
bd dolt stop && bd dolt start
```
**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.
## Database Migrations
After major upgrades, check for database migrations:
```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Preview migration changes
bd migrate --dry-run
# Apply migrations
bd migrate
# Migrate and clean up old files
bd migrate --cleanup --yes
```
## Troubleshooting Upgrades
### Hooks out of date
```bash
bd hooks install
```
### Database schema changed
```bash
bd migrate --dry-run
bd migrate
```
### Recovery after upgrade
If you need to restore from a backup:
```bash
bd init
bd backup restore [path] --force
```
Or pull from a Dolt remote:
```bash
bd dolt pull
```
</document>
<document path="docs/core-concepts/index.md">
# Core Concepts
Understanding the fundamental concepts behind beads.
## Design Philosophy
Beads was built with these principles:
1. **Dolt as source of truth** - Issues stored in a version-controlled SQL database (Dolt), enabling collaboration via Dolt-native replication
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
3. **Local-first operation** - Dolt database for fast queries, background sync
4. **Declarative workflows** - Formulas define repeatable patterns
## Key Components
### Issues
Work items with:
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
- **Priority** - 0 (critical) to 4 (backlog)
- **Status** - `open`, `in_progress`, `closed`
- **Labels** - Flexible tagging
- **Dependencies** - Blocking relationships
### Dependencies
Four types of relationships:
| Type | Description | Affects Ready Queue |
|------|-------------|---------------------|
| `blocks` | Hard dependency (X blocks Y) | Yes |
| `parent-child` | Epic/subtask relationship | No |
| `discovered-from` | Track issues found during work | No |
| `related` | Soft relationship | No |
### Dolt Server Mode
Dolt provides the database backend for beads:
- Start with `bd dolt start`
- Handles auto-commit and sync
- Logs available at `.beads/dolt/sql-server.log`
- Check health with `bd doctor`
### Dolt Sync
The synchronization mechanism:
```
Dolt DB (.beads/dolt/)
↕ dolt commit
Local Dolt history
↕ dolt push/pull
Remote Dolt repository
```
### Formulas
Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations
## Navigation
- [Issues & Dependencies](/core-concepts/issues)
- [Dolt Server Mode](#dolt-server-mode)
- [Dolt Sync](#dolt-sync)
- [Hash-based IDs](/core-concepts/hash-ids)
</document>
<document path="docs/core-concepts/hash-ids.md">
# Hash-based IDs
Understanding beads' collision-resistant ID system.
## The Problem
Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and later merge
## The Solution
Beads uses hash-based IDs:
```
bd-a1b2c3 # Short hash
bd-f14c # Even shorter
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
```
**Properties:**
- Globally unique (content-based hash)
- No coordination needed between creators
- Merge-friendly across branches
- Predictable length (configurable)
## How Hashes Work
IDs are generated from:
- Issue title
- Creation timestamp
- Random salt
```bash
# Create issue - ID assigned automatically
bd create "Fix authentication bug"
# Returns: bd-7x2f
# The ID is deterministic for same content+timestamp
```
## Hierarchical IDs
For epics and subtasks:
```bash
# Parent epic
bd create "Auth System" -t epic
# Returns: bd-a3f8e9
# Children auto-increment
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
```
Benefits:
- Clear parent-child relationship
- No namespace collision (parent hash is unique)
- Up to 3 levels of nesting
## ID Configuration
Configure ID prefix and length:
```bash
# Set prefix (default: bd)
bd config set id.prefix myproject
# Set hash length (default: 4)
bd config set id.hash_length 6
# New issues use new format
bd create "Test"
# Returns: myproject-a1b2c3
```
## Collision Handling
While rare, collisions are handled automatically:
1. On import, if hash collision detected
2. Beads appends disambiguator
3. Both issues preserved
```bash
# Check for collisions
bd info --schema --json | jq '.collision_count'
```
## Working with IDs
```bash
# Partial ID matching
bd show a1b2 # Finds bd-a1b2...
bd show auth # Fuzzy match by title
# Full ID required for ambiguous cases
bd show bd-a1b2c3d4
# List with full IDs
bd list --full-ids
```
## Migration from Sequential IDs
If migrating from a system with sequential IDs:
```bash
# Bootstrap from a JSONL export (preserves original IDs in metadata)
bd init --from-jsonl old-issues.jsonl
# View original ID
bd show bd-new --json | jq '.original_id'
```
## Best Practices
1. **Use short references** - `bd-a1b2` is usually unique enough
2. **Use `--json` for scripts** - Parse full ID programmatically
3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages
4. **Let hierarchies form naturally** - Create epics, add children as needed
</document>
<document path="docs/core-concepts/issues.md">
# Issues & Dependencies
Understanding the issue model in beads.
## Issue Structure
Every issue has:
```bash
bd show bd-42 --json
```
```json
{
"id": "bd-42",
"title": "Implement authentication",
"description": "Add JWT-based auth",
"type": "feature",
"status": "open",
"priority": 1,
"labels": ["backend", "security"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
```
## Issue Types
| Type | Use Case |
|------|----------|
| `bug` | Something broken that needs fixing |
| `feature` | New functionality |
| `task` | Work item (tests, docs, refactoring) |
| `epic` | Large feature with subtasks |
| `chore` | Maintenance (dependencies, tooling) |
## Priorities
| Priority | Level | Examples |
|----------|-------|----------|
| 0 | Critical | Security, data loss, broken builds |
| 1 | High | Major features, important bugs |
| 2 | Medium | Nice-to-have features, minor bugs |
| 3 | Low | Polish, optimization |
| 4 | Backlog | Future ideas |
## Creating Issues
```bash
# Basic issue
bd create "Fix login bug" -t bug -p 1
# With description
bd create "Add password reset" \
--description="Users need to reset forgotten passwords via email" \
-t feature -p 2
# With labels
bd create "Update dependencies" -t chore -l "maintenance,security"
# JSON output for agents
bd create "Task" -t task --json
```
## Dependencies
### Blocking Dependencies
The `blocks` relationship affects the ready queue:
```bash
# Add dependency: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View dependencies
bd dep tree bd-2
# See blocked issues
bd blocked
# See ready work (not blocked)
bd ready
```
### Structural Relationships
These don't affect the ready queue:
```bash
# Parent-child (epic subtasks)
bd create "Epic" -t epic
bd create "Subtask" --parent bd-42
# Discovered-from (found during work)
bd create "Found bug" --deps discovered-from:bd-42
# Related (soft link)
bd relate bd-1 bd-2
```
### Dependency Types
| Type | Description | Ready Queue Impact |
|------|-------------|-------------------|
| `blocks` | Hard dependency | Yes - blocked items not ready |
| `parent-child` | Epic/subtask hierarchy | No |
| `discovered-from` | Tracks origin of discovery | No |
| `related` | Soft relationship | No |
## Hierarchical Issues
For large features, use hierarchical IDs:
```bash
# Create epic
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Child tasks auto-number
bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2
# View hierarchy
bd dep tree bd-a3f8e9
```
## Updating Issues
```bash
# Change status
bd update bd-42 --claim
# Change priority
bd update bd-42 --priority 0
# Add labels
bd update bd-42 --add-label urgent
# Multiple changes
bd update bd-42 --claim --priority 1 --add-label "in-review"
```
## Closing Issues
```bash
# Simple close
bd close bd-42
# With reason
bd close bd-42 --reason "Implemented in PR #123"
# JSON output
bd close bd-42 --json
```
## Searching and Filtering
```bash
# By status
bd list --status open
bd list --status in_progress
# By priority
bd list --priority 1
bd list --priority 0,1 # Multiple
# By type
bd list --type bug
bd list --type feature,task
# By label
bd list --label-any urgent,critical
bd list --label-all backend,security
# Combined filters
bd list --status open --priority 1 --type bug --json
```
</document>
<document path="docs/architecture/index.md">
# Architecture Overview
This document explains how Beads' architecture works with Dolt as its storage backend.
## Architecture
Beads uses **Dolt** as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level.
By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer
setups (multiple agents, orchestrator), switch to **server mode** which connects to a
running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section below for details.
```mermaid
flowchart TD
subgraph DOLT["🗄️ Dolt Database"]
D[(".beads/dolt/<br/><i>Version-Controlled SQL</i>")]
end
subgraph REMOTE["🌐 Dolt Remotes"]
R[("DoltHub / S3 / GCS<br/><i>Sync & Backup</i>")]
end
D <-->|"bd dolt push/pull"| R
U((User)) -->|"bd create<br/>bd update"| D
D -->|"bd list<br/>bd show"| U
style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff
style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff
```
:::info Source of Truth
**Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.
Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`.
:::
### Why Dolt?
- **Version-controlled SQL**: Full SQL queries with native version control
- **Cell-level merge**: Concurrent changes merge automatically at the field level
- **Multi-writer**: Server mode supports concurrent agents
- **Native branching**: Dolt branches independent of git branches
- **Works offline**: All queries run against local database
- **Portable**: `bd export` produces JSONL for migration and interoperability
## Data Flow
### Write Path
```text
User runs bd create
→ Dolt database updated
→ Auto-committed to Dolt history
```
### Read Path
```text
User runs bd list
→ Dolt SQL query
→ Results returned immediately
```
### Sync Path
```text
User runs bd dolt push
→ Commits pushed to Dolt remote
User runs bd dolt pull
→ Remote commits fetched and merged
```
### Multi-Machine Sync Considerations
When working across multiple machines or clones:
1. **Always sync before switching machines**
```bash
bd dolt push # Push changes before leaving
```
2. **Pull before creating new issues**
```bash
bd dolt pull # Pull changes first on new machine
bd create "New issue"
```
3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically
See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3).
## Dolt Server Mode
The Dolt server handles background synchronization and database operations:
- Manages the Dolt database backend
- Handles auto-commit for change tracking
- Provides concurrent access for multiple agents
- Logs available at `.beads/dolt/sql-server.log`
:::tip
Start the Dolt server with `bd dolt start`. Check health with `bd doctor`.
:::
### Embedded Mode (No Server)
For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running:
```bash
bd create "CI-generated issue"
bd dolt push
```
**When embedded mode is appropriate:**
- CI/CD pipelines (Jenkins, GitHub Actions)
- Docker containers
- Ephemeral environments
- Scripts that should not leave background processes
### Multi-Clone Scenarios
:::warning Race Conditions in Multi-Clone Workflows
When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in:
- Multi-agent AI workflows (multiple Claude/GPT instances)
- Developer workstations with multiple checkouts
- Worktree-based development workflows
**Prevention:**
1. Stop the Dolt server (`bd dolt stop`) before switching between clones
2. Dolt handles worktrees natively in server mode
3. Use embedded mode for automated workflows
:::
See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2).
## Recovery Model
Dolt's version control makes recovery straightforward:
1. **Lost database?** → Pull from Dolt remote: `bd dolt pull`
2. **Have a backup?** → Restore it: `bd backup restore [path] --force`
3. **Merge conflicts?** → Dolt handles cell-level merge natively
### Universal Recovery Sequence
The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery).
```bash
bd dolt stop # Stop Dolt server (prevents race conditions)
git worktree prune # Clean orphaned worktrees
bd dolt pull # Pull from Dolt remote
bd dolt start # Restart server
```
:::warning Use `bd doctor --fix` With Care
Always back up and preview before running `bd doctor --fix`:
1. **Back up first:** `cp -r .beads .beads.backup`
2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes
3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made
4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually
**Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you're certain the flagged deps are invalid.
**Other diagnostic tools:**
- `bd blocked` — check which issues are blocked and why
- `bd show <issue-id>` — inspect a specific issue's state
:::
See [Recovery](/recovery) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for Dolt recovery steps.
## Design Decisions
### Why Dolt?
Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics.
### Why not a cloud server?
Beads is designed for offline-first, local-first development. The Dolt server runs locally -- no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks.
### Trade-offs
| Benefit | Trade-off |
|---------|-----------|
| Works offline | No real-time collaboration |
| Version-controlled database | Requires Dolt server |
| Cell-level merge | Requires initial setup |
| Local-first speed | Manual sync to remotes |
| SQL queries | Dolt binary dependency |
### When NOT to use Beads
Beads is not suitable for:
- **Large teams (10+)** — Git-based sync doesn't scale well for high-frequency concurrent edits
- **Non-developers** — Requires Git and command-line familiarity
- **Real-time collaboration** — No live updates; requires explicit sync
- **Cross-repository tracking** — Issues are scoped to a single repository
- **Rich media attachments** — Designed for text-based issue tracking
For these use cases, consider GitHub Issues, Linear, or Jira.
## Related Documentation
- [Recovery Runbooks](/recovery) — Step-by-step procedures for common issues
- [CLI Reference](/cli-reference) — Complete command documentation
- [Getting Started](/) — Installation and first steps
</document>
<document path="docs/cli-reference/index.md">
# CLI Reference
Complete reference for all `bd` commands.
## Command Structure
```bash
bd [global-flags] <command> [command-flags] [arguments]
```
### Global Flags
| Flag | Description |
|------|-------------|
| `--db <path>` | Use specific database file |
| `--json` | Output in JSON format |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Verbose output |
| `--version` | Show version |
| `--help` | Show help |
## Command Categories
### Essential Commands
Most frequently used:
| Command | Description |
|---------|-------------|
| `bd create` | Create new issue |
| `bd list` | List issues with filters |
| `bd show` | Show issue details |
| `bd update` | Update issue fields |
| `bd close` | Close an issue |
| `bd ready` | Show unblocked work |
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
### Issue Management
| Command | Description |
|---------|-------------|
| `bd create` | Create issue |
| `bd show` | Show details |
| `bd update` | Update fields |
| `bd close` | Close issue |
| `bd delete` | Delete issue |
| `bd reopen` | Reopen closed issue |
### Dependencies
| Command | Description |
|---------|-------------|
| `bd dep add` | Add dependency |
| `bd dep remove` | Remove dependency |
| `bd dep tree` | Show dependency tree |
| `bd dep cycles` | Detect circular dependencies |
| `bd blocked` | Show blocked issues |
| `bd ready` | Show unblocked issues |
### Labels & Comments
| Command | Description |
|---------|-------------|
| `bd label add` | Add label to issue |
| `bd label remove` | Remove label |
| `bd label list` | List all labels |
| `bd comment add` | Add comment |
| `bd comment list` | List comments |
### Sync & Export
| Command | Description |
|---------|-------------|
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
| `bd export` | Export data to JSONL |
| `bd migrate` | Migrate database schema |
### System
| Command | Description |
|---------|-------------|
| `bd init` | Initialize beads in project |
| `bd info` | Show system info |
| `bd version` | Show version |
| `bd config` | Manage configuration |
| `bd doctor` | Check system health |
| `bd hooks` | Manage git hooks |
### Workflows
| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol` | Manage molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |
## Quick Reference
### Creating Issues
```bash
# Basic
bd create "Title" -t task -p 2
# With description
bd create "Title" --description="Details here" -t bug -p 1
# With labels
bd create "Title" -l "backend,urgent"
# As child of epic
bd create "Subtask" --parent bd-42
# With discovered-from link
bd create "Found bug" --deps discovered-from:bd-42
# JSON output
bd create "Title" --json
```
### Querying Issues
```bash
# All open issues
bd list --status open
# High priority bugs
bd list --status open --priority 0,1 --type bug
# With specific labels
bd list --label-any urgent,critical
# JSON output
bd list --json
```
### Working with Dependencies
```bash
# Add: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View tree
bd dep tree bd-2
# Find cycles
bd dep cycles
# What's ready to work?
bd ready
# What's blocked?
bd blocked
```
### Syncing
```bash
# Push changes to Dolt remote
bd dolt push
# Pull changes from Dolt remote
bd dolt pull
# Export to file
bd export -o backup.jsonl
```
## See Also
- [Essential Commands](/cli-reference/essential)
- [Issue Commands](/cli-reference/issues)
- [Dependency Commands](/cli-reference/dependencies)
- [Label Commands](/cli-reference/labels)
- [Sync Commands](/cli-reference/sync)
</document>
<document path="docs/cli-reference/dependencies.md">
# Dependency Commands
Commands for managing issue dependencies.
## bd dep add
Add a dependency between issues.
```bash
bd dep add <dependent> <dependency> [flags]
```
**Semantics:** `<dependent>` depends on `<dependency>` (dependency blocks dependent).
**Flags:**
```bash
--type Dependency type (blocks|related|discovered-from)
--json JSON output
```
**Examples:**
```bash
# bd-2 depends on bd-1 (bd-1 blocks bd-2)
bd dep add bd-2 bd-1
# Soft relationship
bd dep add bd-2 bd-1 --type related
# JSON output
bd dep add bd-2 bd-1 --json
```
## bd dep remove
Remove a dependency.
```bash
bd dep remove <dependent> <dependency> [flags]
```
**Examples:**
```bash
bd dep remove bd-2 bd-1
bd dep remove bd-2 bd-1 --json
```
## bd dep tree
Display dependency tree.
```bash
bd dep tree <id> [flags]
```
**Flags:**
```bash
--depth Maximum depth to display
--json JSON output
```
**Examples:**
```bash
bd dep tree bd-42
bd dep tree bd-42 --depth 3
bd dep tree bd-42 --json
```
**Output:**
```
Dependency tree for bd-42:
> bd-42: Add authentication [P2] (open)
> bd-41: Create API [P2] (open)
> bd-40: Set up database [P1] (closed)
```
## bd dep cycles
Detect circular dependencies.
```bash
bd dep cycles [flags]
```
**Flags:**
```bash
--json JSON output
```
**Examples:**
```bash
bd dep cycles
bd dep cycles --json
```
## bd ready
Show issues with no blockers.
```bash
bd ready [flags]
```
**Flags:**
```bash
--priority Filter by priority
--type Filter by type
--label Filter by label
--json JSON output
```
**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --type bug
bd ready --json
```
**Output:**
```
Ready work (3 issues with no blockers):
1. [P1] bd-40: Set up database
2. [P2] bd-45: Write tests
3. [P3] bd-46: Update docs
```
## bd blocked
Show blocked issues and their blockers.
```bash
bd blocked [flags]
```
**Flags:**
```bash
--json JSON output
```
**Examples:**
```bash
bd blocked
bd blocked --json
```
**Output:**
```
Blocked issues (2 issues):
bd-42: Add authentication
Blocked by: bd-41 (open)
bd-41: Create API
Blocked by: bd-40 (in_progress)
```
## bd relate
Create a soft relationship between issues.
```bash
bd relate <id1> <id2> [flags]
```
**Examples:**
```bash
bd relate bd-42 bd-43
bd relate bd-42 bd-43 --json
```
## bd duplicate
Mark an issue as duplicate.
```bash
bd duplicate <id> --of <canonical> [flags]
```
**Examples:**
```bash
bd duplicate bd-43 --of bd-42
bd duplicate bd-43 --of bd-42 --json
```
## bd supersede
Mark an issue as superseding another.
```bash
bd supersede <old> --with <new> [flags]
```
**Examples:**
```bash
bd supersede bd-42 --with bd-50
bd supersede bd-42 --with bd-50 --json
```
## Understanding Dependencies
### Blocking vs Non-blocking
| Type | Blocks Ready Queue | Use Case |
|------|-------------------|----------|
| `blocks` | Yes | Hard dependency |
| `parent-child` | No | Epic/subtask hierarchy |
| `discovered-from` | No | Track origin |
| `related` | No | Soft link |
| `duplicates` | No | Mark duplicate |
| `supersedes` | No | Version chain |
### Dependency Direction
```bash
# bd-2 depends on bd-1
# Meaning: bd-1 must complete before bd-2 can start
bd dep add bd-2 bd-1
# After bd-1 closes:
bd close bd-1
bd ready # bd-2 now appears
```
### Avoiding Cycles
```bash
# Check before adding complex dependencies
bd dep cycles
# If cycle detected, remove one dependency
bd dep remove bd-A bd-B
```
</document>
<document path="docs/cli-reference/essential.md">
# Essential Commands
The most important commands for daily use.
## bd create
Create a new issue.
```bash
bd create <title> [flags]
```
**Flags:**
| Flag | Short | Description |
|------|-------|-------------|
| `--type` | `-t` | Issue type: bug, feature, task, epic, chore |
| `--priority` | `-p` | Priority: 0-4 (0=critical, 4=backlog) |
| `--description` | `-d` | Detailed description |
| `--labels` | `-l` | Comma-separated labels |
| `--parent` | | Parent issue ID (for hierarchical) |
| `--deps` | | Dependencies (e.g., `discovered-from:bd-42`) |
| `--json` | | JSON output |
**Examples:**
```bash
bd create "Fix login bug" -t bug -p 1
bd create "Add dark mode" -t feature -p 2 --description="User requested"
bd create "Subtask" --parent bd-42 -p 2
bd create "Found during work" --deps discovered-from:bd-42 --json
```
## bd list
List issues with filters.
```bash
bd list [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | Filter by status: open, in_progress, closed |
| `--priority` | Filter by priority (comma-separated) |
| `--type` | Filter by type (comma-separated) |
| `--label-any` | Issues with any of these labels |
| `--label-all` | Issues with all of these labels |
| `--json` | JSON output |
**Examples:**
```bash
bd list --status open
bd list --priority 0,1 --type bug
bd list --label-any urgent,critical --json
```
## bd show
Show issue details.
```bash
bd show <id> [flags]
```
**Examples:**
```bash
bd show bd-42
bd show bd-42 --json
bd show bd-42 bd-43 bd-44 # Multiple issues
```
## bd update
Update issue fields.
```bash
bd update <id> [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | New status |
| `--priority` | New priority |
| `--title` | New title |
| `--description` | New description |
| `--add-label` | Add label |
| `--remove-label` | Remove label |
| `--json` | JSON output |
**Examples:**
```bash
bd update bd-42 --claim
bd update bd-42 --priority 0 --add-label urgent
bd update bd-42 --title "Updated title" --json
```
## bd close
Close an issue.
```bash
bd close <id> [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--reason` | Closure reason |
| `--json` | JSON output |
**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in PR #123"
bd close bd-42 --json
```
## bd ready
Show issues ready to work on (no blockers).
```bash
bd ready [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--priority` | Filter by priority |
| `--type` | Filter by type |
| `--json` | JSON output |
**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --json
```
## bd blocked
Show blocked issues and their blockers.
```bash
bd blocked [flags]
```
**Examples:**
```bash
bd blocked
bd blocked --json
```
## bd dolt push
Push changes to a Dolt remote.
```bash
bd dolt push [flags]
```
Performs:
1. Dolt commit (snapshot current database state)
2. Push to Dolt remote
**Examples:**
```bash
bd dolt push
```
## bd dolt pull
Pull changes from a Dolt remote.
```bash
bd dolt pull [flags]
```
**Examples:**
```bash
bd dolt pull
```
## bd info
Show system information.
```bash
bd info [flags]
```
**Flags:**
| Flag | Description |
|------|-------------|
| `--whats-new` | Show recent version changes |
| `--schema` | Show database schema |
| `--json` | JSON output |
**Examples:**
```bash
bd info
bd info --whats-new
bd info --json
```
## bd stats
Show project statistics.
```bash
bd stats [flags]
```
**Examples:**
```bash
bd stats
bd stats --json
```
</document>
<document path="docs/cli-reference/issues.md">
# Issue Commands
Commands for managing issues.
## bd create
Create a new issue.
```bash
bd create <title> [flags]
```
**All flags:**
```bash
--type, -t Issue type (bug|feature|task|epic|chore)
--priority, -p Priority 0-4
--description, -d Detailed description
--design Design notes
--acceptance Acceptance criteria
--notes Additional notes
--labels, -l Comma-separated labels
--parent Parent issue ID
--deps Dependencies (type:id format)
--assignee Assigned user
--json JSON output
```
**Examples:**
```bash
# Bug with high priority
bd create "Login fails with special chars" -t bug -p 1
# Feature with description
bd create "Add export to PDF" -t feature -p 2 \
--description="Users want to export reports as PDF files"
# Feature with design, acceptance, and notes
bd create "Implement user authentication" -t feature -p 1 \
--description="Add JWT-based authentication" \
--design="Use bcrypt for password hashing, JWT for sessions" \
--acceptance="All tests pass, security audit complete" \
--notes="Consider rate limiting for login attempts"
# Task with labels
bd create "Update CI config" -t task -l "ci,infrastructure"
# Epic with children
bd create "Auth System" -t epic -p 1
bd create "Design login UI" --parent bd-42
bd create "Implement backend" --parent bd-42
# Discovered issue
bd create "Found SQL injection" -t bug -p 0 \
--deps discovered-from:bd-42 --json
```
## bd show
Display issue details.
```bash
bd show <id>... [flags]
```
**Flags:**
```bash
--full Show all fields including comments
--json JSON output
```
**Examples:**
```bash
bd show bd-42
bd show bd-42 --full
bd show bd-42 bd-43 bd-44 --json
```
## bd update
Update issue fields.
```bash
bd update <id> [flags]
```
**All flags:**
```bash
--status New status (open|in_progress|closed)
--priority New priority (0-4)
--title New title
--description New description
--type New type
--add-label Add label(s)
--remove-label Remove label(s)
--assignee New assignee
--json JSON output
```
**Examples:**
```bash
# Start work
bd update bd-42 --claim
# Escalate priority
bd update bd-42 --priority 0 --add-label urgent
# Change title and description
bd update bd-42 --title "New title" --description="Updated description"
# Multiple changes
bd update bd-42 --claim --priority 1 --add-label "in-review" --json
```
## bd close
Close an issue.
```bash
bd close <id> [flags]
```
**Flags:**
```bash
--reason Closure reason (stored in comment)
--json JSON output
```
**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in commit abc123"
bd close bd-42 --reason "Duplicate of bd-43" --json
```
## bd reopen
Reopen a closed issue.
```bash
bd reopen <id> [flags]
```
**Examples:**
```bash
bd reopen bd-42
bd reopen bd-42 --json
```
## bd delete
Delete an issue.
```bash
bd delete <id> [flags]
```
**Flags:**
```bash
--force, -f Skip confirmation
--json JSON output
```
**Examples:**
```bash
bd delete bd-42
bd delete bd-42 -f --json
```
**Note:** Deletions are tracked in the Dolt database for sync.
## bd search
Search issues by text.
```bash
bd search <query> [flags]
```
**Flags:**
```bash
--status Filter by status
--type Filter by type
--json JSON output
```
**Examples:**
```bash
bd search "authentication"
bd search "login bug" --status open
bd search "API" --type feature --json
```
## bd duplicates
Find and manage duplicate issues.
```bash
bd duplicates [flags]
```
**Flags:**
```bash
--auto-merge Automatically merge all duplicates
--dry-run Preview without changes
--json JSON output
```
**Examples:**
```bash
bd duplicates
bd duplicates --auto-merge
bd duplicates --dry-run --json
```
## bd merge
Merge duplicate issues.
```bash
bd merge <source>... --into <target> [flags]
```
**Flags:**
```bash
--into Target issue to merge into
--dry-run Preview without changes
--json JSON output
```
**Examples:**
```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run --json
```
</document>
<document path="docs/cli-reference/labels.md">
# Labels & Comments
Commands for managing labels and comments.
## Labels
### Adding Labels
```bash
# During creation
bd create "Task" -l "backend,urgent"
# To existing issue
bd update bd-42 --add-label urgent
bd update bd-42 --add-label "backend,security"
```
### Removing Labels
```bash
bd update bd-42 --remove-label urgent
```
### Listing Labels
```bash
# All labels in use
bd label list
bd label list --json
# Issues with specific labels
bd list --label-any urgent,critical
bd list --label-all backend,security
```
### Label Conventions
Suggested label categories:
| Category | Examples | Purpose |
|----------|----------|---------|
| Type | `bug`, `feature`, `docs` | Issue classification |
| Priority | `urgent`, `critical` | Urgency markers |
| Area | `backend`, `frontend`, `api` | Code area |
| Status | `blocked`, `needs-review` | Workflow state |
| Size | `small`, `medium`, `large` | Effort estimate |
## Comments
### Adding Comments
```bash
bd comment add bd-42 "Working on this now"
bd comment add bd-42 --message "Found the bug in auth.go:45"
```
### Listing Comments
```bash
bd comment list bd-42
bd comment list bd-42 --json
```
### Viewing with Issue
```bash
bd show bd-42 --full # Includes comments
```
## Filtering by Labels
### Any Match (OR)
```bash
# Issues with urgent OR critical
bd list --label-any urgent,critical
```
### All Match (AND)
```bash
# Issues with BOTH backend AND security
bd list --label-all backend,security
```
### Combined Filters
```bash
# Open bugs with urgent label
bd list --status open --type bug --label-any urgent --json
```
## Bulk Operations
### Add Label to Multiple Issues
```bash
# Using shell
for id in bd-42 bd-43 bd-44; do
bd update $id --add-label "sprint-1"
done
```
### Find and Label
```bash
# Label all open bugs as needs-triage
bd list --status open --type bug --json | \
jq -r '.[].id' | \
xargs -I {} bd update {} --add-label needs-triage
```
## Best Practices
1. **Keep labels lowercase** - `backend` not `Backend`
2. **Use hyphens for multi-word** - `needs-review` not `needs_review`
3. **Be consistent** - Establish team conventions
4. **Don't over-label** - 2-4 labels per issue is typical
5. **Review periodically** - Remove unused labels
</document>
<document path="docs/cli-reference/sync.md">
# Sync & Export Commands
Commands for synchronizing with Dolt.
## bd dolt push
Push changes to a Dolt remote.
```bash
bd dolt push [flags]
```
**What it does:**
1. Dolt commit (snapshot current database state)
2. Push commits to Dolt remote
**Examples:**
```bash
bd dolt push
```
**When to use:**
- End of work session
- Before switching machines
- After significant changes
## bd dolt pull
Pull changes from a Dolt remote.
```bash
bd dolt pull [flags]
```
**What it does:**
1. Fetches commits from Dolt remote
2. Merges into local database
**Examples:**
```bash
bd dolt pull
```
**When to use:**
- Start of work session
- After switching machines
- Before creating new issues (to avoid duplicates)
## bd export
Export database to JSONL format (for backup and migration).
```bash
bd export [flags]
```
**Flags:**
```bash
--output, -o Output file (default: stdout)
--dry-run Preview without writing
--json JSON output
```
**Examples:**
```bash
bd export
bd export -o backup.jsonl
bd export --dry-run
```
**When to use:** `bd export` is for backup and data migration, not day-to-day sync. Dolt handles sync natively via `bd dolt push`/`bd dolt pull`.
## bd migrate
Migrate database schema.
```bash
bd migrate [flags]
```
**Flags:**
```bash
--inspect Show migration plan (for agents)
--dry-run Preview without changes
--cleanup Remove old files after migration
--yes Skip confirmation
--json JSON output
```
**Examples:**
```bash
bd migrate --inspect --json
bd migrate --dry-run
bd migrate
bd migrate --cleanup --yes
```
## bd hooks
Manage git hooks.
```bash
bd hooks <subcommand> [flags]
```
**Subcommands:**
| Command | Description |
|---------|-------------|
| `install` | Install git hooks |
| `uninstall` | Remove git hooks |
| `status` | Check hook status |
**Examples:**
```bash
bd hooks install
bd hooks status
bd hooks uninstall
```
## Auto-Sync Behavior
### With Dolt Server Mode (Default)
When the Dolt server is running, sync is handled automatically:
- Dolt auto-commit tracks changes
- Dolt-native replication handles remote sync
Start the Dolt server with `bd dolt start`.
### Embedded Mode (No Server)
In CI/CD pipelines and ephemeral environments, no server is needed:
- Changes written directly to the database
- Must manually push to remote
```bash
bd create "CI-generated task"
bd dolt push # Manual push needed
```
## Conflict Resolution
Dolt handles conflict resolution at the database level using its built-in
merge capabilities. When conflicts arise during `bd dolt pull`, Dolt identifies
conflicting rows and allows resolution through SQL.
```bash
# Check for conflicts after pull
bd doctor --fix
```
## Deletion Tracking
Deletions are tracked in the Dolt database:
```bash
# Delete issue
bd delete bd-42
# View deletions
bd deleted
bd deleted --since=30d
# Deletions propagate via Dolt push
bd dolt push
```
## Best Practices
1. **Always push at session end** - `bd dolt push`
2. **Always pull at session start** - `bd dolt pull`
3. **Install git hooks** - `bd hooks install`
4. **Check sync status** - `bd info` shows sync state
</document>
<document path="docs/workflows/index.md">
# Workflows
Beads provides powerful workflow primitives for complex, multi-step processes.
## Chemistry Metaphor
Beads uses a molecular chemistry metaphor for workflow phases:
| Phase | Command | Synced | Use Case |
|-------|---------|--------|----------|
| **Proto** (solid) | `bd cook` | N/A | Compiled template, reusable |
| **Mol** (liquid) | `bd mol pour` | Yes | Persistent work with audit trail |
| **Wisp** (vapor) | `bd mol wisp` | No | Ephemeral operations |
## Core Concepts
### Formulas
Declarative workflow templates in TOML or JSON. Support variables, conditional steps, loops, inheritance, and composition.
```toml
formula = "feature-workflow"
version = 1
type = "workflow"
[[steps]]
id = "design"
title = "Design the feature"
type = "human"
[[steps]]
id = "implement"
title = "Implement the feature"
needs = ["design"]
```
### Cooking
`bd cook` compiles a formula into a resolved proto. Two modes: compile-time (keeps `{{var}}` placeholders for planning) and runtime (substitutes all variables for final output).
### Molecules
Work graphs with parent-child relationships:
- Created by instantiating formulas with `bd mol pour`
- Steps have dependencies (`needs`)
- Progress tracked via issue status
### Gates
Async coordination primitives:
- **Human gates** - Wait for human approval
- **Timer gates** - Wait for duration
- **GitHub gates** - Wait for PR merge, CI, etc.
### Wisps
Ephemeral operations that don't sync:
- Created with `bd mol wisp`
- Stored locally with `Ephemeral=true`
- Lifecycle: squash (promote), burn (discard), or GC (auto-clean)
### Swarms
Parallel execution across an epic's dependency graph:
- Analyze epic structure for parallelism: `bd swarm validate`
- Create coordinated swarm from epic: `bd swarm create`
- Monitor progress across waves: `bd swarm status`
## Workflow Commands
| Command | Description |
|---------|-------------|
| `bd cook` | Compile formula into proto |
| `bd mol pour` | Instantiate formula as persistent molecule |
| `bd mol wisp` | Create ephemeral wisp from formula |
| `bd mol list` | List molecules |
| `bd mol squash` | Promote wisp to persistent molecule |
| `bd mol burn` | Delete wisp without trace |
| `bd mol wisp gc` | Garbage collect old wisps |
| `bd mol bond` | Bond formulas together with phase control |
| `bd swarm validate` | Analyze epic for parallel execution |
| `bd swarm create` | Create swarm from epic |
| `bd swarm status` | Show swarm progress |
| `bd swarm list` | List all swarm molecules |
| `bd formula list` | List available formulas |
## Simple Example
```bash
# Create a release workflow
bd mol pour release --var version=1.0.0
# View the molecule
bd dep tree bd-xyz
# Work through steps
bd update bd-xyz.1 --claim
bd close bd-xyz.1
# Next step becomes ready...
```
## Navigation
- [Molecules](/workflows/molecules) - Work graphs and execution
- [Formulas](/workflows/formulas) - Declarative templates (types, variables, inheritance, loops, conditions)
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral operations (squash, burn, GC lifecycle)
</document>
<document path="docs/workflows/formulas.md">
# Formulas
Formulas are declarative workflow templates.
## Formula Format
Formulas can be written in TOML (preferred) or JSON:
### TOML Format
```toml
formula = "feature-workflow"
description = "Standard feature development workflow"
version = 1
type = "workflow"
[vars.feature_name]
description = "Name of the feature"
required = true
[[steps]]
id = "design"
title = "Design {{feature_name}}"
type = "human"
description = "Create design document"
[[steps]]
id = "implement"
title = "Implement {{feature_name}}"
needs = ["design"]
[[steps]]
id = "review"
title = "Code review"
needs = ["implement"]
type = "human"
[[steps]]
id = "merge"
title = "Merge to main"
needs = ["review"]
```
### JSON Format
```json
{
"formula": "feature-workflow",
"description": "Standard feature development workflow",
"version": 1,
"type": "workflow",
"vars": {
"feature_name": {
"description": "Name of the feature",
"required": true
}
},
"steps": [
{
"id": "design",
"title": "Design {{feature_name}}",
"type": "human"
},
{
"id": "implement",
"title": "Implement {{feature_name}}",
"needs": ["design"]
}
]
}
```
## Formula Types
| Type | Description |
|------|-------------|
| `workflow` | Standard step sequence |
| `expansion` | Template for expansion operator |
| `aspect` | Cross-cutting concerns |
| `convoy` | Multi-agent coordination (parallel workers) |
### Convoy Formulas
Convoy formulas coordinate multiple agents working in parallel. Use them for code review with multiple reviewers, design review sessions, or any workflow requiring parallel human or agent coordination.
```toml
formula = "multi-reviewer"
description = "Parallel code review with multiple reviewers"
version = 1
type = "convoy"
[vars.reviewers]
description = "Comma-separated reviewer names"
required = true
[[steps]]
id = "review-setup"
title = "Prepare review artifacts"
[[steps]]
id = "collect"
title = "Collect reviews"
needs = ["review-setup"]
waits_for = "all-children"
```
## Variables
Define variables with defaults and constraints:
```toml
[vars.version]
description = "Release version"
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"
[vars.environment]
description = "Target environment"
default = "staging"
enum = ["staging", "production"]
```
Use variables in steps:
```toml
[[steps]]
title = "Deploy {{version}} to {{environment}}"
```
## Step Types
| Type | Description |
|------|-------------|
| `task` | Normal work step (default) |
| `human` | Requires human action |
| `gate` | Async coordination point |
## Dependencies
### Sequential
```toml
[[steps]]
id = "step1"
title = "First step"
[[steps]]
id = "step2"
title = "Second step"
needs = ["step1"]
```
### Parallel then Join
```toml
[[steps]]
id = "test-unit"
title = "Unit tests"
[[steps]]
id = "test-integration"
title = "Integration tests"
[[steps]]
id = "deploy"
title = "Deploy"
needs = ["test-unit", "test-integration"] # Waits for both
```
## Conditional Steps
Steps can be made conditional based on a variable:
```toml
[vars.run_security_scan]
description = "Whether to run security scan"
default = "true"
[[steps]]
id = "security-scan"
title = "Run security scan"
condition = "{{run_security_scan}}"
[[steps]]
id = "deploy"
title = "Deploy to production"
condition = "{{environment}} == production"
```
Condition formats:
- `"{{var}}"` - truthy (non-empty, non-false)
- `"!{{var}}"` - negated
- `"{{var}} == value"` - equality
- `"{{var}} != value"` - inequality
Conditions are evaluated at cook/pour time. Steps that don't match are removed from the workflow.
## Loops and Iteration
Steps can iterate using the `loop` field:
### Fixed Count
```toml
[[steps]]
id = "retry"
title = "Attempt {{i}}"
[steps.loop]
count = 3
var = "i"
[[steps.loop.body]]
id = "try-{{i}}"
title = "Attempt {{i}}"
```
### Range
```toml
[[steps]]
id = "phases"
title = "Phase iteration"
[steps.loop]
range = "1..5"
var = "phase_num"
[[steps.loop.body]]
id = "phase-{{phase_num}}"
title = "Execute phase {{phase_num}}"
```
Range supports expressions: `"1..2^{disks}"`, `"{start}..{count}"`.
### Until (Conditional)
```toml
[steps.loop]
until = "step.status == 'complete'"
max = 10
var = "attempt"
[[steps.loop.body]]
id = "attempt-{{attempt}}"
title = "Attempt {{attempt}}"
```
The `max` field is required for `until` loops to prevent unbounded iteration.
## Runtime Expansion (on_complete)
Steps can trigger dynamic work when they complete using `on_complete` with `for_each`:
```toml
[[steps]]
id = "survey"
title = "Survey available workers"
[steps.on_complete]
for_each = "output.workers"
bond = "worker-arm"
parallel = true
[steps.on_complete.vars]
worker_name = "{item.name}"
rig = "{item.rig}"
```
This creates a new molecule from the `worker-arm` formula for each item in the `output.workers` array. Use `sequential = true` instead of `parallel` to run them one at a time.
## Formula Inheritance
Formulas can inherit from parent formulas using `extends`:
```toml
formula = "secure-release"
description = "Release with security audit"
version = 1
type = "workflow"
extends = ["release"]
# Inherits all vars and steps from "release"
# Add new steps or override existing ones by ID:
[[steps]]
id = "security-audit"
title = "Security audit"
needs = ["test"]
# Override parent step
[[steps]]
id = "publish"
title = "Publish release (with audit)"
needs = ["tag", "security-audit"]
```
Child formulas inherit all vars, steps, and compose rules from parents. Child definitions with the same ID override parent definitions.
## Cooking Formulas
`bd cook` compiles a formula into a resolved proto. Two modes:
### Compile-time (default)
Produces a proto with `{{variable}}` placeholders intact. Useful for modeling, estimation, and planning.
```bash
bd cook feature-workflow # Template with placeholders
bd cook feature-workflow --dry-run # Preview steps
```
### Runtime
Produces a fully-resolved proto with variables substituted. Requires all variables to have values.
```bash
bd cook feature-workflow --var feature_name=auth # Substitute vars
bd cook feature-workflow --mode=runtime --var name=x # Explicit runtime
```
For most workflows, prefer using `bd pour` or `bd mol wisp` directly - they cook the formula inline.
## Gates
Add gates for async coordination:
```toml
[[steps]]
id = "approval"
title = "Manager approval"
type = "human"
[steps.gate]
type = "human"
approvers = ["manager"]
[[steps]]
id = "deploy"
title = "Deploy to production"
needs = ["approval"]
```
Gate types: `human`, `timer`, `gh:run` (GitHub Actions), `gh:pr` (pull request).
## Aspects (Cross-cutting)
Apply transformations to matching steps:
```toml
formula = "security-scan"
type = "aspect"
[[advice]]
target = "*.deploy" # Match all deploy steps
[advice.before]
id = "security-scan-{step.id}"
title = "Security scan before {step.title}"
```
Aspects support `before`, `after`, and `around` advice. Apply aspects to a formula via `compose.aspects`:
```toml
[compose]
aspects = ["security-scan", "logging"]
```
## Formula Locations
Formulas are searched in order:
1. `.beads/formulas/` (project-level)
2. `~/.beads/formulas/` (user-level)
## Using Formulas
```bash
# List available formulas
bd formula list
# Cook (compile) a formula
bd cook <formula-name> [--var key=value]
# Pour formula into molecule (persistent)
bd mol pour <formula-name> --var key=value
# Create wisp from formula (ephemeral)
bd mol wisp <formula-name> --var key=value
# Preview what would be created
bd mol pour <formula-name> --dry-run
```
## Creating Custom Formulas
1. Create file: `.beads/formulas/my-workflow.formula.toml`
2. Define structure (see examples above)
3. Use with: `bd mol pour my-workflow`
## Example: Release Formula
```toml
formula = "release"
description = "Standard release workflow"
version = 1
[vars.version]
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"
[[steps]]
id = "bump-version"
title = "Bump version to {{version}}"
[[steps]]
id = "changelog"
title = "Update CHANGELOG"
needs = ["bump-version"]
[[steps]]
id = "test"
title = "Run full test suite"
needs = ["changelog"]
[[steps]]
id = "build"
title = "Build release artifacts"
needs = ["test"]
[[steps]]
id = "tag"
title = "Create git tag v{{version}}"
needs = ["build"]
[[steps]]
id = "publish"
title = "Publish release"
needs = ["tag"]
type = "human"
```
</document>
<document path="docs/workflows/gates.md">
# Gates
Gates are async coordination primitives for workflow orchestration.
## What are Gates?
Gates block step progression until a condition is met:
- Human approval
- Timer expiration
- External event (GitHub PR, CI, etc.)
## Gate Types
### Human Gate
Wait for human approval:
```toml
[[steps]]
id = "deploy-approval"
title = "Approval for production deploy"
type = "human"
[steps.gate]
type = "human"
approvers = ["team-lead", "security"]
require_all = false # Any approver can approve
```
### Timer Gate
Wait for a duration:
```toml
[[steps]]
id = "cooldown"
title = "Wait for cooldown period"
[steps.gate]
type = "timer"
duration = "24h"
```
Durations: `30m`, `2h`, `24h`, `7d`
### GitHub Gate
Wait for GitHub events:
```toml
[[steps]]
id = "wait-for-ci"
title = "Wait for CI to pass"
[steps.gate]
type = "github"
event = "check_suite"
status = "success"
```
```toml
[[steps]]
id = "wait-for-merge"
title = "Wait for PR merge"
[steps.gate]
type = "github"
event = "pull_request"
action = "closed"
merged = true
```
## Gate States
| State | Description |
|-------|-------------|
| `pending` | Waiting for condition |
| `open` | Condition met, can proceed |
| `closed` | Step completed |
## Using Gates in Workflows
### Approval Flow
```toml
formula = "production-deploy"
[[steps]]
id = "build"
title = "Build production artifacts"
[[steps]]
id = "staging"
title = "Deploy to staging"
needs = ["build"]
[[steps]]
id = "qa-approval"
title = "QA sign-off"
needs = ["staging"]
type = "human"
[steps.gate]
type = "human"
approvers = ["qa-team"]
[[steps]]
id = "production"
title = "Deploy to production"
needs = ["qa-approval"]
```
### Scheduled Release
```toml
formula = "scheduled-release"
[[steps]]
id = "prepare"
title = "Prepare release"
[[steps]]
id = "wait-window"
title = "Wait for release window"
needs = ["prepare"]
[steps.gate]
type = "timer"
duration = "2h"
[[steps]]
id = "deploy"
title = "Deploy release"
needs = ["wait-window"]
```
### CI Integration
```toml
formula = "ci-gated-deploy"
[[steps]]
id = "create-pr"
title = "Create pull request"
[[steps]]
id = "wait-ci"
title = "Wait for CI"
needs = ["create-pr"]
[steps.gate]
type = "github"
event = "check_suite"
status = "success"
[[steps]]
id = "merge"
title = "Merge PR"
needs = ["wait-ci"]
type = "human"
```
## Gate Operations
### Check Gate Status
```bash
bd show bd-xyz.3 # Shows gate state
bd show bd-xyz.3 --json | jq '.gate'
```
### Manual Gate Override
For human gates:
```bash
bd gate approve bd-xyz.3 --approver "team-lead"
```
### Skip Gate (Emergency)
```bash
bd gate skip bd-xyz.3 --reason "Emergency deploy"
```
## waits-for Dependency
The `waits-for` dependency type creates fan-in patterns:
```toml
[[steps]]
id = "test-a"
title = "Test suite A"
[[steps]]
id = "test-b"
title = "Test suite B"
[[steps]]
id = "integration"
title = "Integration tests"
waits_for = ["test-a", "test-b"] # Fan-in: waits for all
```
## Best Practices
1. **Use human gates for critical decisions** - Don't auto-approve production
2. **Add timeout to timer gates** - Prevent indefinite blocking
3. **Document gate requirements** - Make approvers clear
4. **Use CI gates for quality** - Block on test failures
</document>
<document path="docs/workflows/molecules.md">
# Molecules
Molecules are work graphs created from formulas.
## What is a Molecule?
A molecule is a persistent instance of a formula:
- Contains steps with dependencies
- Tracked in `.beads/` (syncs with git)
- Steps map to issues with parent-child relationships
## Creating Molecules
### From Formula
```bash
# Pour a formula into a molecule
bd pour <formula-name> [--var key=value]
```
**Example:**
```bash
bd pour release --var version=1.0.0
```
This creates:
- Parent issue: `bd-xyz` (the molecule root)
- Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps)
### Listing Molecules
```bash
bd mol list
bd mol list --json
```
### Viewing a Molecule
```bash
bd mol show <molecule-id>
bd dep tree <molecule-id> # Shows full hierarchy
```
## Working with Molecules
### Step Dependencies
Steps have `needs` dependencies:
```toml
[[steps]]
id = "implement"
title = "Implement feature"
needs = ["design"] # Must complete design first
```
The `bd ready` command respects these:
```bash
bd ready # Only shows steps with completed dependencies
```
### Progressing Through Steps
```bash
# Start a step
bd update bd-xyz.1 --claim
# Complete a step
bd close bd-xyz.1 --reason "Done"
# Check what's ready next
bd ready
```
### Viewing Progress
```bash
# See blocked steps
bd blocked
# See molecule stats
bd stats
```
## Molecule Lifecycle
```
Formula (template)
↓ bd pour
Molecule (instance)
↓ work steps
Completed Molecule
↓ optional cleanup
Archived
```
## Advanced Features
### Bond Points
Formulas can define bond points for composition:
```toml
[compose]
[[compose.bond_points]]
id = "entry"
step = "design"
position = "before"
```
### Hooks
Execute actions on step completion:
```toml
[[steps]]
id = "build"
title = "Build project"
[steps.on_complete]
run = "make build"
```
### Pinning Work
Assign molecules to agents:
```bash
# Pin to current agent
bd pin bd-xyz --start
# Check what's pinned
bd hook
```
## Example Workflow
```bash
# 1. Create molecule from formula
bd pour feature-workflow --var name="dark-mode"
# 2. View structure
bd dep tree bd-xyz
# 3. Start first step
bd update bd-xyz.1 --claim
# 4. Complete and progress
bd close bd-xyz.1
bd ready # Shows next steps
# 5. Continue until complete
```
## See Also
- [Formulas](/workflows/formulas) - Creating templates
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral workflows
</document>
<document path="docs/workflows/wisps.md">
# Wisps
Wisps are ephemeral workflows that don't sync to git.
## What are Wisps?
Wisps are "vapor phase" molecules - issues stored with `Ephemeral=true` in the main database. They are local-only and not synced via Dolt push/pull.
## Use Cases
| Scenario | Why Wisp? |
|----------|-----------|
| Release workflows | One-time execution, no audit trail needed |
| Operational loops | Recurring cycles that auto-clean up |
| Health checks | Diagnostics that shouldn't clutter history |
| Local experiments | Quick throwaway work |
| Agent coordination | Local-only parallel coordination |
## Creating Wisps
```bash
# Create wisp from formula
bd mol wisp <formula> [--var key=value]
# Examples
bd mol wisp quick-check
bd mol wisp release --var version=1.0.0
```
Formulas can recommend wisp usage with `phase = "vapor"` in the formula definition. If you use `bd mol pour` on a vapor-phase formula, you'll get a warning suggesting `bd mol wisp` instead.
## Wisp Lifecycle
```
Formula (template)
| bd mol wisp
v
Wisp (ephemeral, Ephemeral=true)
| normal bd operations
v
Completed Wisp
|
+---> bd mol squash (promote to persistent molecule)
+---> bd mol burn (delete without trace)
+---> bd mol wisp gc (garbage collect old wisps)
```
### Squash (Promote to Persistent)
Convert a wisp into a regular persistent molecule. Clears the `Ephemeral` flag so the issue syncs to git. Use when ephemeral work turns out to be worth preserving.
```bash
bd mol squash <wisp-id>
```
### Burn (Delete Without Trace)
Delete a wisp and all its children without creating a digest or summary. Use for discarding failed or abandoned ephemeral work.
```bash
bd mol burn <wisp-id>
```
### Garbage Collection
Clean up old, orphaned, or completed wisps automatically:
```bash
# List all wisps (flags old ones > 24h)
bd mol wisp list
# Garbage collect orphaned wisps
bd mol wisp gc
```
Wisps older than 24 hours are flagged as "old" in list output.
## Wisp Commands
```bash
bd mol wisp <formula> # Create wisp from formula
bd mol wisp list # List all wisps
bd mol wisp list --json # List in JSON format
bd mol wisp gc # Garbage collect old wisps
bd mol squash <wisp-id> # Promote to persistent
bd mol burn <wisp-id> # Delete without digest
```
## Wisp vs Molecule
| Aspect | Molecule (pour) | Wisp |
|--------|-----------------|------|
| Phase | Liquid | Vapor |
| Persistence | Permanent, syncs via Dolt | Ephemeral, local-only |
| Use case | Tracked work, audit trail | Temporary ops, one-time runs |
| Cleanup | Manual close/archive | Squash, burn, or GC |
## Phase Control
Use `bd mol bond` to control phase when bonding formulas together:
```bash
# Force liquid (persistent molecule)
bd mol bond <formula> <target> --pour
# Force vapor (ephemeral wisp)
bd mol bond <formula> <target> --wisp
```
## Best Practices
1. **Default to wisp for operational work** - releases, checks, diagnostics
2. **Use pour for tracked work** - features, bugs, anything worth preserving
3. **Squash if work becomes valuable** - promote ephemeral to persistent
4. **Burn failed experiments** - clean up without cluttering history
5. **Run GC periodically** - `bd mol wisp gc` keeps the database lean
</document>
<document path="docs/multi-agent/index.md">
# Multi-Agent Coordination
Beads supports coordination between multiple AI agents and repositories.
## Overview
Multi-agent features enable:
- **Routing** - Automatic issue routing to correct repositories
- **Cross-repo dependencies** - Dependencies across repository boundaries
- **Agent coordination** - Work assignment and handoff between agents
## Key Concepts
### Routes
Routes define which repository handles which issues:
```jsonl
{"pattern": "frontend/*", "target": "frontend-repo"}
{"pattern": "backend/*", "target": "backend-repo"}
{"pattern": "*", "target": "main-repo"}
```
### Work Assignment
Pin work to specific agents:
```bash
bd pin bd-42 --for agent-1 --start
bd hook --agent agent-1 # Show pinned work
```
### Cross-repo Dependencies
Track dependencies across repositories:
```bash
bd dep add bd-42 external:other-repo/bd-100
```
## Architecture
```
┌─────────────────┐
│ Main Repo │
│ (coordinator) │
└────────┬────────┘
│ routes
┌────┴────┐
│ │
┌───▼───┐ ┌───▼───┐
│Frontend│ │Backend│
│ Repo │ │ Repo │
└────────┘ └────────┘
```
## Getting Started
1. **Single repo**: Standard beads workflow
2. **Multi-repo**: Configure routes and cross-repo deps
3. **Multi-agent**: Add work assignment and handoff
## Navigation
- [Routing](/multi-agent/routing) - Auto-routing configuration
- [Coordination](/multi-agent/coordination) - Agent coordination patterns
</document>
<document path="docs/multi-agent/coordination.md">
# Agent Coordination
Patterns for coordinating work between multiple AI agents.
## Work Assignment
### Pinning Work
Assign work to a specific agent:
```bash
# Pin issue to agent
bd pin bd-42 --for agent-1
# Pin and start work
bd pin bd-42 --for agent-1 --start
# Unpin work
bd unpin bd-42
```
### Checking Pinned Work
```bash
# What's on my hook?
bd hook
# What's on agent-1's hook?
bd hook --agent agent-1
# JSON output
bd hook --json
```
## Handoff Patterns
### Sequential Handoff
Agent A completes work, hands off to Agent B:
```bash
# Agent A
bd close bd-42 --reason "Ready for review"
bd pin bd-42 --for agent-b
# Agent B picks up
bd hook # Sees bd-42
bd update bd-42 --claim
```
### Parallel Work
Multiple agents work on different issues:
```bash
# Coordinator
bd pin bd-42 --for agent-a --start
bd pin bd-43 --for agent-b --start
bd pin bd-44 --for agent-c --start
# Each agent works independently
# Coordinator monitors progress
bd list --status in_progress --json
```
### Fan-Out / Fan-In
Split work, then merge:
```bash
# Fan-out
bd create "Part A" --parent bd-epic
bd create "Part B" --parent bd-epic
bd create "Part C" --parent bd-epic
bd pin bd-epic.1 --for agent-a
bd pin bd-epic.2 --for agent-b
bd pin bd-epic.3 --for agent-c
# Fan-in: wait for all parts
bd dep add bd-merge bd-epic.1 bd-epic.2 bd-epic.3
```
## Agent Discovery
Find available agents:
```bash
# List known agents (if using agent registry)
bd agents list
# Check agent status
bd agents status agent-1
```
## Conflict Prevention
### File Reservations
Prevent concurrent edits:
```bash
# Reserve files before editing
bd reserve auth.go --for agent-1
# Check reservations
bd reservations list
# Release when done
bd reserve --release auth.go
```
### Issue Locking
```bash
# Lock issue for exclusive work
bd lock bd-42 --for agent-1
# Unlock when done
bd unlock bd-42
```
## Communication Patterns
### Via Comments
```bash
# Agent A leaves note
bd comment add bd-42 "Completed API, needs frontend integration"
# Agent B reads
bd show bd-42 --full
```
### Via Labels
```bash
# Mark for review
bd update bd-42 --add-label "needs-review"
# Agent B filters
bd list --label-any needs-review
```
## Best Practices
1. **Clear ownership** - Always pin work to specific agent
2. **Document handoffs** - Use comments to explain context
3. **Use labels for status** - `needs-review`, `blocked`, `ready`
4. **Avoid conflicts** - Use reservations for shared files
5. **Monitor progress** - Regular status checks
</document>
<document path="docs/multi-agent/routing.md">
# Multi-Repo Routing
Automatic issue routing across repositories.
## Overview
Routing enables:
- Issues created in one repo routed to another
- Pattern-based routing rules
- Fallback to default repository
## Configuration
Create `.beads/routes.jsonl`:
```jsonl
{"pattern": "frontend/**", "target": "frontend-repo", "priority": 10}
{"pattern": "backend/**", "target": "backend-repo", "priority": 10}
{"pattern": "docs/**", "target": "docs-repo", "priority": 5}
{"pattern": "*", "target": "main-repo", "priority": 0}
```
## Route Fields
| Field | Description |
|-------|-------------|
| `pattern` | Glob pattern to match |
| `target` | Target repository |
| `priority` | Higher = checked first |
## Pattern Matching
Patterns match against:
- Issue title
- Labels
- Explicit path prefix
**Examples:**
```jsonl
{"pattern": "frontend/*", "target": "frontend"}
{"pattern": "*api*", "target": "backend"}
{"pattern": "label:docs", "target": "docs-repo"}
```
## Commands
```bash
# Show routing table
bd routes list
bd routes list --json
# Test routing
bd routes test "Fix frontend button"
bd routes test --label frontend
# Add route
bd routes add "frontend/**" --target frontend-repo --priority 10
# Remove route
bd routes remove "frontend/**"
```
## Auto-Routing
When creating issues, beads checks routes:
```bash
bd create "Fix frontend button alignment" -t bug
# Auto-routed to frontend-repo based on title match
```
Override with explicit target:
```bash
bd create "Fix button" --repo backend-repo
```
## Cross-Repo Dependencies
Track dependencies across repos:
```bash
# In frontend-repo
bd dep add bd-42 external:backend-repo/bd-100
# View cross-repo deps
bd dep tree bd-42 --cross-repo
```
## Hydration
Pull related issues from other repos:
```bash
# Hydrate issues from related repos
bd hydrate
# Preview hydration
bd hydrate --dry-run
# Hydrate specific repo
bd hydrate --from backend-repo
```
## Best Practices
1. **Use specific patterns** - Avoid overly broad matches
2. **Set priorities** - Ensure specific patterns match first
3. **Default fallback** - Always have a `*` pattern with lowest priority
4. **Test routes** - Use `bd routes test` before committing
</document>
<document path="docs/integrations/aider.md">
# Aider Integration
How to use beads with Aider.
## Setup
### Quick Setup
```bash
bd setup aider
```
This creates/updates `.aider.conf.yml` with beads context.
### Verify Setup
```bash
bd setup aider --check
```
## Configuration
The setup adds to `.aider.conf.yml`:
```yaml
# Beads integration — bd prime provides issue context
auto-commits: false
```
## Workflow
### Start Session
```bash
# Aider will have access to issues via .aider.conf.yml
aider
# Or manually inject context
bd prime | aider --message-file -
```
### During Work
Use bd commands alongside aider:
```bash
# In another terminal or after exiting aider
bd create "Found bug during work" --deps discovered-from:bd-42 --json
bd update bd-42 --claim
bd ready
```
### End Session
```bash
bd dolt push
```
## Best Practices
1. **Keep issues visible** - Use `bd prime` to inject issue context
2. **Push regularly** - Run `bd dolt push` after significant changes
3. **Use discovered-from** - Track issues found during work
4. **Document context** - Include descriptions in issues
## Example Workflow
```bash
# 1. Check ready work
bd ready
# 2. Start aider with issue context
aider --message "Working on bd-42: Fix auth bug"
# 3. Work in aider...
# 4. Create discovered issues
bd create "Found related bug" --deps discovered-from:bd-42 --json
# 5. Complete and push
bd close bd-42 --reason "Fixed"
bd dolt push
```
## Troubleshooting
### Config not loading
```bash
# Check config exists
cat .aider.conf.yml
# Regenerate
bd setup aider
```
### Issues not visible
```bash
# Use bd prime to inject issue context
bd prime | aider --message-file -
# Or check database health
bd doctor
```
## See Also
- [Claude Code](/integrations/claude-code)
- [IDE Setup](/getting-started/ide-setup)
</document>
<document path="docs/integrations/claude-code.md">
# Claude Code Integration
How to use beads with Claude Code.
## Setup
### Quick Setup
```bash
bd setup claude
```
This installs:
- **SessionStart hook** - Runs `bd prime` on session start
- **PreCompact hook** - Runs `bd dolt push` before context compaction
### Manual Setup
Add to your Claude Code hooks configuration:
```json
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd dolt push"]
}
}
```
### Verify Setup
```bash
bd setup claude --check
```
## How It Works
1. **Session starts** → `bd prime` injects ~1-2k tokens of context
2. **You work** → Use `bd` CLI commands directly
3. **Session compacts** → `bd dolt push` saves work to Dolt remote
4. **Session ends** → Changes synced via git
## Essential Commands for Agents
### Creating Issues
```bash
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
```
### Working on Issues
```bash
# Find ready work
bd ready --json
# Start work
bd update bd-42 --claim --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```
### Querying
```bash
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
```
### Syncing
```bash
# ALWAYS run at session end
bd dolt push
```
## Best Practices
### Always Use `--json`
```bash
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
```
### Always Include Descriptions
```bash
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```
### Link Related Work
```bash
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Push Before Session End
```bash
# ALWAYS run before ending
bd dolt push
```
## Plugin (Optional)
For enhanced UX with slash commands:
```bash
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
# Restart Claude Code
```
Adds slash commands:
- `/beads:ready` - Show ready work
- `/beads:create` - Create issue
- `/beads:show` - Show issue
- `/beads:update` - Update issue
- `/beads:close` - Close issue
## Troubleshooting
### Context not injected
```bash
# Check hook setup
bd setup claude --check
# Manually prime
bd prime
```
### Changes not syncing
```bash
# Force push
bd dolt push
# Check system health
bd doctor
```
### Database not found
```bash
# Initialize beads
bd init --quiet
```
## See Also
- [MCP Server](/integrations/mcp-server) - For MCP-only environments
- [IDE Setup](/getting-started/ide-setup) - Other editors
</document>
<document path="docs/integrations/github-copilot.md">
# GitHub Copilot Integration
How to use beads with GitHub Copilot in VS Code.
## Setup
### Quick Setup
1. Install beads-mcp:
```bash
uv tool install beads-mcp
```
2. Create `.vscode/mcp.json` in your project:
```json
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**For all projects:** Add to VS Code user-level MCP config:
| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |
```json
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
```
3. Initialize beads:
```bash
bd init --quiet
```
4. Reload VS Code
### Verify Setup
Ask Copilot Chat: "What beads issues are ready to work on?"
## Using Natural Language
With MCP configured, interact naturally:
```
You: Create a bug for the login timeout
Copilot: Created bd-42: Login timeout bug
You: What issues are ready?
Copilot: 3 issues ready: bd-42, bd-99, bd-17
You: Close bd-42, it's fixed
Copilot: Closed bd-42
```
## MCP Tools
| Tool | Description |
|------|-------------|
| `beads_ready` | List unblocked issues |
| `beads_create` | Create new issue |
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_dolt_push` | Push to Dolt remote |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |
## Copilot Instructions
Optionally add `.github/copilot-instructions.md`:
```markdown
## Issue Tracking
This project uses **bd (beads)** for issue tracking.
Run `bd prime` for workflow context.
Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push changes to Dolt remote
```
## Troubleshooting
### Tools not appearing
1. Check VS Code 1.96+
2. Verify mcp.json syntax is valid JSON
3. Reload VS Code window
4. Check Output panel for MCP errors
### "beads-mcp not found"
```bash
# Check installation
which beads-mcp
# Reinstall if needed
uv tool install beads-mcp --force
```
### No database found
```bash
bd init --quiet
```
## FAQ
### Do I need to clone beads?
**No.** Beads is a system-wide CLI tool. Install once, use everywhere. The `.beads/` directory in your project only contains the issue database.
### What about git hooks?
Git hooks are optional. They auto-sync issues but you can skip them during `bd init` and manually run `bd dolt push` / `bd dolt pull` instead.
## See Also
- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
- [Installation](/getting-started/installation) - Full install guide
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
</document>
<document path="docs/integrations/junie.md">
# Junie Integration
How to use beads with Junie (JetBrains AI Agent).
## Setup
### Quick Setup
```bash
bd setup junie
```
This creates:
- **`.junie/guidelines.md`** - Agent instructions for beads workflow
- **`.junie/mcp/mcp.json`** - MCP server configuration
### Verify Setup
```bash
bd setup junie --check
```
## How It Works
1. **Session starts** → Junie reads `.junie/guidelines.md` for workflow context
2. **MCP tools available** → Junie can use beads MCP tools directly
3. **You work** → Use `bd` CLI commands or MCP tools
4. **Session ends** → Run `bd dolt push` to push changes to Dolt remote
## Configuration Files
### Guidelines (`.junie/guidelines.md`)
Contains workflow instructions that Junie reads automatically:
- Core workflow rules
- Command reference
- Issue types and priorities
- MCP tool documentation
### MCP Config (`.junie/mcp/mcp.json`)
Configures the beads MCP server:
```json
{
"mcpServers": {
"beads": {
"command": "bd",
"args": ["mcp"]
}
}
}
```
## MCP Tools
With MCP configured, Junie can use these tools directly:
| Tool | Description |
| --- | --- |
| `mcp_beads_ready` | Find tasks ready for work |
| `mcp_beads_list` | List issues with filters |
| `mcp_beads_show` | Show issue details |
| `mcp_beads_create` | Create new issues |
| `mcp_beads_update` | Update issue status/priority |
| `mcp_beads_close` | Close completed issues |
| `mcp_beads_dep` | Manage dependencies |
| `mcp_beads_blocked` | Show blocked issues |
| `mcp_beads_stats` | Get issue statistics |
## CLI Commands
You can also use the `bd` CLI directly:
### Creating Issues
```bash
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
```
### Working on Issues
```bash
# Find ready work
bd ready --json
# Start work
bd update bd-42 --claim --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```
### Querying
```bash
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
```
### Syncing
```bash
# ALWAYS run at session end
bd dolt push
```
## Best Practices
### Always Use `--json`
```bash
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
```
### Always Include Descriptions
```bash
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```
### Link Related Work
```bash
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Push Before Session End
```bash
# ALWAYS run before ending
bd dolt push
```
## Troubleshooting
### Guidelines not loaded
```bash
# Check setup
bd setup junie --check
# Reinstall if needed
bd setup junie
```
### MCP tools not available
```bash
# Verify MCP config exists
cat .junie/mcp/mcp.json
# Test MCP server
bd mcp --help
```
### Changes not syncing
```bash
# Force push
bd dolt push
# Check system health
bd doctor
```
### Database not found
```bash
# Initialize beads
bd init --quiet
```
## Removing Integration
```bash
bd setup junie --remove
```
This removes:
- `.junie/guidelines.md`
- `.junie/mcp/mcp.json`
- Empty `.junie/mcp/` and `.junie/` directories
## See Also
- [MCP Server](/integrations/mcp-server) - MCP server details
- [Claude Code](/integrations/claude-code) - Similar hook-based integration
- [IDE Setup](/getting-started/ide-setup) - Other editors
</document>
<document path="docs/integrations/mcp-server.md">
# MCP Server
Use beads in MCP-only environments.
## When to Use MCP
Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments
**Prefer CLI + hooks** when shell is available - it's more context efficient.
## Installation
### Using uv (Recommended)
```bash
uv tool install beads-mcp
```
### Using pip
```bash
pip install beads-mcp
```
## Configuration
### Claude Desktop (macOS)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
### Claude Desktop (Windows)
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
### Sourcegraph Amp
Add to MCP settings:
```json
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
### VS Code / GitHub Copilot
Create `.vscode/mcp.json` in your project:
```json
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
```
**For all projects:** Add to VS Code user-level MCP config:
| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |
```json
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
```
**Note:** Requires VS Code 1.96+ with MCP support enabled.
See [GitHub Copilot Integration](/integrations/github-copilot) for complete setup guide.
## Available Tools
The MCP server exposes these tools:
| Tool | Description |
|------|-------------|
| `beads_create` | Create new issue |
| `beads_list` | List issues |
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_ready` | Show ready work |
| `beads_sync` | Sync to git |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |
## Usage
Once configured, use naturally:
```
Create an issue for fixing the login bug with priority 1
```
The MCP server translates to appropriate `bd` commands.
## Trade-offs
| Aspect | CLI + Hooks | MCP Server |
|--------|-------------|------------|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |
## Troubleshooting
### Server won't start
Check if `beads-mcp` is in PATH:
```bash
which beads-mcp
```
If not found:
```bash
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
```
### Tools not appearing
1. Restart Claude Desktop
2. Check MCP config JSON syntax
3. Verify server path
### Permission errors
```bash
# Check directory permissions
ls -la .beads/
# Initialize if needed
bd init --quiet
```
## See Also
- [Claude Code](/integrations/claude-code) - CLI integration
- [Installation](/getting-started/installation) - Full install guide
</document>
<document path="docs/recovery/index.md">
# Recovery Overview
This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention.
## Common Issues
| Issue | Symptoms | Runbook |
|-------|----------|---------|
| Database Corruption | SQLite errors, missing data | [Database Corruption](/recovery/database-corruption) |
| Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
| Circular Dependencies | Cycle detection errors | [Circular Dependencies](/recovery/circular-dependencies) |
| Sync Failures | `bd dolt push`/`bd dolt pull` errors | [Sync Failures](/recovery/sync-failures) |
## Quick Diagnostic
Before diving into specific runbooks, try these quick checks:
```bash
# Check Beads status
bd status
# Verify Dolt server is running
bd doctor
# Check for blocked issues
bd blocked
```
:::tip
Most issues can be diagnosed with `bd status`. Start there before following specific runbooks.
:::
## Getting Help
If these runbooks don't resolve your issue:
1. Check the [FAQ](/reference/faq)
2. Search [existing issues](https://github.com/gastownhall/beads/issues)
3. Open a new issue with diagnostic output
</document>
<document path="docs/recovery/circular-dependencies.md">
# Circular Dependencies Recovery
This runbook helps you detect and break circular dependency cycles in your issues.
## Symptoms
- "circular dependency detected" errors
- `bd blocked` shows unexpected results
- Issues that should be ready appear blocked
## Diagnosis
```bash
# Check for blocked issues
bd blocked
# View dependencies for a specific issue
bd show <issue-id>
# List all dependencies
bd dep tree
```
## Solution
**Step 1:** Identify the cycle
```bash
bd blocked --verbose
```
**Step 2:** Map the dependency chain
```bash
bd show <issue-a>
bd show <issue-b>
# Follow the chain until you return to <issue-a>
```
**Step 3:** Determine which dependency to remove
Consider: Which dependency is least critical to the workflow?
**Step 4:** Remove the problematic dependency
```bash
bd dep remove <dependent-issue> <blocking-issue>
```
**Step 5:** Verify the cycle is broken
```bash
bd blocked
bd ready
```
## Prevention
- Think "X needs Y" not "X before Y" when adding dependencies
- Use `bd blocked` after adding dependencies to check for cycles
- Keep dependency chains shallow when possible
</document>
<document path="docs/recovery/database-corruption.md">
# Database Corruption Recovery
This runbook helps you recover from database corruption in Beads.
## Symptoms
- Error messages during `bd` commands
- "database is locked" errors that persist
- Missing issues that should exist
- Inconsistent database state
## Diagnosis
```bash
# Check database integrity
bd doctor
# Check Dolt server health
bd dolt show
```
## Solution
**Step 1:** Stop the Dolt server
```bash
bd dolt stop
```
**Step 2:** Back up current state
```bash
cp -r .beads .beads.backup
```
**Step 3:** Preview what doctor would fix
```bash
bd doctor --dry-run
```
**Step 4:** Rebuild database
```bash
bd doctor --fix
```
**Step 5:** Verify recovery
```bash
bd doctor
bd list
```
**Step 6:** Restart the Dolt server
```bash
dolt sql-server
```
## Prevention
- Let the Dolt server handle synchronization
- Use `bd dolt stop` before system shutdown
- Run `bd doctor` periodically to catch issues early
</document>
<document path="docs/recovery/merge-conflicts.md">
# Merge Conflicts Recovery
This runbook helps you resolve merge conflicts that occur during Dolt sync operations.
## Symptoms
- `bd dolt pull` fails with conflict errors
- Different issue states between clones
## Diagnosis
```bash
# Check database health
bd doctor
# Preview what fixes would be applied
bd doctor --dry-run
```
## Solution
**Step 1:** Back up current state
```bash
cp -r .beads .beads.backup
```
**Step 2:** Check for conflicts
```bash
bd doctor
```
**Step 3:** Fix to reconcile
```bash
bd doctor --fix
```
**Step 4:** Verify state
```bash
bd list
bd stats
```
**Step 5:** Push resolved state
```bash
bd dolt push
```
## Prevention
- Sync before and after work sessions using `bd dolt pull` / `bd dolt push`
- Avoid concurrent modifications from multiple clones without the Dolt server running
</document>
<document path="docs/recovery/sync-failures.md">
# Sync Failures Recovery
This runbook helps you recover from Dolt sync failures.
## Symptoms
- `bd dolt push` or `bd dolt pull` hangs or times out
- Network-related error messages
- "failed to push" or "failed to pull" errors
- Dolt server not responding
## Diagnosis
```bash
# Check Dolt server health
bd doctor
bd dolt show
# View Dolt server logs
tail -50 .beads/dolt/sql-server.log
```
## Solution
**Step 1:** Stop the Dolt server
```bash
bd dolt stop
```
**Step 2:** Check for lock files
```bash
ls -la .beads/*.lock
# Remove stale locks if Dolt server is definitely stopped
rm -f .beads/*.lock
```
**Step 3:** Back up and preview fixes
```bash
cp -r .beads .beads.backup
bd doctor --dry-run
```
**Step 4:** Apply fixes if needed
```bash
bd doctor --fix
```
**Step 5:** Restart the Dolt server
```bash
dolt sql-server
```
**Step 6:** Verify sync works
```bash
bd dolt push
bd doctor
```
## Common Causes
| Cause | Solution |
|-------|----------|
| Network timeout | Retry with better connection |
| Stale lock file | Remove lock after stopping Dolt server |
| Corrupted state | Back up, then `bd doctor --fix` |
| Merge conflicts | See [Merge Conflicts](/recovery/merge-conflicts) |
## Prevention
- Ensure stable network before sync
- Let sync complete before closing terminal
- Use `bd dolt stop` before system shutdown
</document>
<document path="docs/reference/advanced.md">
# Advanced Features
Advanced beads functionality.
## Issue Rename
Rename issues while preserving references:
```bash
bd rename bd-42 bd-new-id
bd rename bd-42 bd-new-id --dry-run # Preview
```
Updates:
- All dependencies pointing to old ID
- All references in other issues
- Comments and descriptions
## Issue Merge
Merge duplicate issues:
```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run
```
What gets merged:
- Dependencies → target
- Text references updated across all issues
- Source issues closed with merge reason
## Database Compaction
Reduce database size by compacting old issues:
```bash
# View compaction statistics
bd admin compact --stats
# Preview candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediate deletion (CAUTION!)
bd admin cleanup --force
```
**When to compact:**
- Database > 10MB with old closed issues
- After major milestones
- Before archiving project phase
## Restore from History
View deleted or compacted issues from git:
```bash
bd restore bd-42 --show
bd restore bd-42 --to-file issue.json
```
## Database Inspection
```bash
# Schema info
bd info --schema --json
# Raw database query (advanced — requires dolt sql-server running)
bd dolt sql "SELECT * FROM issues LIMIT 5"
```
## Custom Tables
Extend the database with custom tables:
```go
// In Go code using beads as library
storage.UnderlyingDB().Exec(`
CREATE TABLE IF NOT EXISTS custom_table (...)
`)
```
See [EXTENDING.md](https://github.com/gastownhall/beads/blob/main/docs/EXTENDING.md).
## Event System
Subscribe to beads events:
```bash
# View recent events
bd events list --since 1h
# Watch events in real-time
bd events watch
```
Events:
- `issue.created`
- `issue.updated`
- `issue.closed`
- `dependency.added`
- `sync.completed`
## Batch Operations
### Create Multiple
```bash
# Bootstrap a new database from JSONL
bd init --from-jsonl issues.jsonl
```
### Update Multiple
```bash
bd list --status open --priority 4 --json | \
jq -r '.[].id' | \
xargs -I {} bd update {} --priority 3
```
### Close Multiple
```bash
bd list --label "sprint-1" --status open --json | \
jq -r '.[].id' | \
xargs -I {} bd close {} --reason "Sprint complete"
```
## API Access
Use beads as a Go library:
```go
import "github.com/steveyegge/beads/internal/storage/embeddeddolt"
store, _ := embeddeddolt.New(ctx, ".beads", "beads", "main")
defer store.Close()
issue, _ := store.GetIssue(ctx, "bd-a1b2")
```
## Performance Tuning
### Large Databases
```bash
# Enable WAL mode
bd config set database.wal_mode true
# Increase cache
bd config set database.cache_size 10000
```
### Many Concurrent Agents
Beads uses Dolt server mode to handle concurrent access from multiple agents.
The server manages transaction isolation automatically.
```bash
# Start the Dolt server
bd dolt start
# Check server health
bd doctor
```
### CI/CD Optimization
In CI/CD environments, beads uses embedded mode by default (no server required):
```bash
# Just run commands directly — no special flags needed
bd list
```
</document>
<document path="docs/reference/configuration.md">
# Configuration
Complete configuration reference for beads.
## Configuration Locations
1. **Project config**: `.beads/config.toml` (highest priority)
2. **User config**: `~/.beads/config.toml`
3. **Environment variables**: `BEADS_*`
4. **Command-line flags**: (highest priority)
## Managing Configuration
```bash
# Get config value
bd config get import.orphan_handling
# Set config value
bd config set import.orphan_handling allow
# List all config
bd config list
# Reset to default
bd config reset import.orphan_handling
```
## Configuration Options
### Database
```toml
[database]
# Embedded mode (default): data stored in .beads/embeddeddolt/
# Server mode: connects to dolt sql-server (bd init --server)
```
### ID Generation
```toml
[id]
prefix = "bd" # Issue ID prefix
hash_length = 4 # Hash length in IDs
```
**Issue ID mode** controls whether new issues get hash-based or sequential IDs:
```bash
# Use sequential IDs: bd-1, bd-2, bd-3, ...
bd config set issue_id_mode counter
# Use hash-based IDs (default): bd-a3f2, bd-7f3a8, ...
bd config set issue_id_mode hash
```
| Mode | Example ID | Best for |
|------|-----------|----------|
| `hash` (default) | `bd-a3f2` | Multi-agent, multi-branch workflows |
| `counter` | `bd-1` | Single-writer, project-management UIs |
Counter IDs are sequential and human-friendly. Hash IDs are collision-free across concurrent
branches. See [CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md) for migration guidance and full details.
### Import
```toml
[import]
orphan_handling = "allow" # allow|resurrect|skip|strict
dedupe_on_import = false # Run duplicate detection after import
```
| Mode | Behavior |
|------|----------|
| `allow` | Import orphans without validation (default) |
| `resurrect` | Restore deleted parents as tombstones |
| `skip` | Skip orphaned children with warning |
| `strict` | Fail if parent missing |
### Export
```toml
[export]
path = ".beads/issues.jsonl" # Default export file path (for bd export command)
```
### Git
```toml
[git]
auto_commit = true # Auto-commit on sync
auto_push = true # Auto-push on sync
commit_message = "bd: auto-commit" # Default commit message
```
### Hooks
```toml
[hooks]
pre_commit = true # Enable pre-commit hook
post_merge = true # Enable post-merge hook
pre_push = true # Enable pre-push hook
```
### Deletions
```toml
[deletions]
retention_days = 30 # Keep deletion records for N days
prune_on_sync = true # Auto-prune old records
```
## Environment Variables
| Variable | Description |
|----------|-------------|
| `BEADS_DB` | Database path |
| `BEADS_LOG_LEVEL` | Log level |
| `BEADS_CONFIG` | Config file path |
## Per-Command Override
```bash
# Override database
bd --db /tmp/test.db list
```
## Example Configuration
`.beads/config.toml`:
```toml
[id]
prefix = "myproject"
hash_length = 6
[import]
orphan_handling = "resurrect"
dedupe_on_import = true
[git]
auto_commit = true
auto_push = true
[deletions]
retention_days = 90
```
## Viewing Active Configuration
```bash
bd info --json | jq '.config'
```
</document>
<document path="docs/reference/faq.md">
# Frequently Asked Questions
## General
### Why beads instead of GitHub Issues or Jira?
Beads was designed specifically for AI-supervised coding workflows:
- **Hash-based IDs** prevent collisions with concurrent agents
- **Dolt-backed storage** enables branch-based workflows
- **Dependency-aware** ready queue for automated work selection
- **Formula system** for declarative workflow templates
### What does "beads" stand for?
Nothing specific - it's a metaphor for linked work items (like beads on a string).
### Is beads production-ready?
Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning.
## Architecture
### Why Dolt instead of plain SQLite?
- **Dolt** provides a version-controlled SQL database with built-in replication
- Git-like branching, diffing, and merging at the database level
- No need for a separate sync format -- Dolt handles it natively
### Why hash-based IDs instead of sequential?
Sequential IDs (`#1`, `#2`) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and merge
Hash-based IDs are globally unique without coordination.
### How does the Dolt server work?
Beads uses Dolt server mode for concurrent access:
- Transaction isolation for multiple agents
- SQL-based queries for performance
- Automatic retry on conflicts
In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required).
## Usage
### How do I sync issues?
```bash
# Push changes to Dolt remote:
bd dolt push
# Pull changes from Dolt remote:
bd dolt pull
```
### How do I handle merge conflicts?
Dolt handles merge conflicts at the database level. If conflicts arise during pull:
```bash
bd doctor --fix
bd dolt push
```
### Can multiple agents work on the same repo?
Yes! That's what beads was designed for:
- Hash IDs prevent collisions
- Pin work to specific agents
- Track who's working on what
### How do I use beads in CI/CD?
```bash
# Just run commands directly — beads uses embedded mode in CI
bd list
```
## Workflows
### What are formulas?
Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).
### What are gates?
Async coordination primitives:
- Human gates wait for approval
- Timer gates wait for duration
- GitHub gates wait for CI/PR events
### What's the difference between molecules and wisps?
- **Molecules** persist in `.beads/` and sync with git
- **Wisps** are ephemeral in `.beads-wisp/` and don't sync
## Integration
### Should I use CLI or MCP?
**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.):
- Lower context overhead (~1-2k vs 10-50k tokens)
- Faster execution
- Universal across editors
**Use MCP** when CLI unavailable (Claude Desktop).
### How do I integrate with my editor?
```bash
bd setup claude # Claude Code
bd setup cursor # Cursor
bd setup aider # Aider
```
### Can beads import from GitHub Issues?
Yes — see the [GitHub integration documentation](https://github.com/gastownhall/beads/blob/main/docs/GITHUB_IMPORT.md) for details.
## Troubleshooting
### Why is the Dolt server not starting?
```bash
# Check server status
bd doctor
# Check server logs
cat .beads/dolt/sql-server.log
# Restart the server
bd dolt stop
bd dolt start
```
### Why aren't my changes syncing?
```bash
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
```
### How do I report a bug?
1. Check existing issues: https://github.com/gastownhall/beads/issues
2. Include: `bd version`, `bd info --json`, reproduction steps
3. File at: https://github.com/gastownhall/beads/issues/new
</document>
<document path="docs/reference/git-integration.md">
# Git Integration
How beads integrates with git.
## Overview
Beads uses git for:
- **Project hosting** - Your code repository also hosts beads configuration
- **Hooks** - Auto-sync on git operations
Data storage and sync are handled by Dolt (a version-controlled SQL database).
## File Structure
```
.beads/
├── config.toml # Project config (git-tracked)
├── metadata.json # Backend metadata (git-tracked)
└── dolt/ # Dolt database and server data (gitignored)
```
## Git Hooks
### Installation
```bash
bd hooks install
```
Installs:
- **pre-commit** - Triggers Dolt commit
- **post-merge** - Triggers Dolt sync after pull
- **pre-push** - Ensures Dolt sync before push
### Status
```bash
bd hooks status
```
### Uninstall
```bash
bd hooks uninstall
```
## Conflict Resolution
Dolt handles merge conflicts at the database level using its built-in
merge capabilities. When conflicts arise during sync, Dolt identifies
conflicting rows and allows resolution through SQL.
```bash
# Check for and fix conflicts
bd doctor --fix
```
## Protected Branches
Dolt stores data under `refs/dolt/data`, separate from Git refs. This means beads data doesn't conflict with protected Git branches — no special branch flag is needed.
## Git Worktrees
Beads works in git worktrees using embedded mode:
```bash
# In worktree — just run commands directly
bd create "Task"
bd list
```
## Branch Workflows
### Feature Branch
```bash
git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd dolt push
git push
```
### Fork Workflow
```bash
# In fork
bd init --contributor
# Work in separate planning repo...
bd dolt push
```
### Team Workflow
```bash
bd init --team
# All team members share the Dolt database
bd dolt pull # Pull latest changes from Dolt remote
bd dolt push # Push your changes to Dolt remote
```
### Duplicate Detection
After merging branches:
```bash
bd duplicates --auto-merge
```
## Best Practices
1. **Install hooks** - `bd hooks install`
2. **Push regularly** - `bd dolt push` at session end
3. **Pull before work** - `bd dolt pull` to get latest issues
4. **Worktrees use embedded mode automatically**
</document>
<document path="docs/reference/troubleshooting.md">
# Troubleshooting
Common issues and solutions.
## Installation Issues
### `bd: command not found`
```bash
# Check if installed
which bd
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
```
### `zsh: killed bd` on macOS
CGO/SQLite compatibility issue:
```bash
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```
### Permission denied
```bash
chmod +x $(which bd)
```
## Database Issues
### Database not found
```bash
# Initialize beads
bd init --quiet
# Or specify database
bd --db .beads/beads.db list
```
### Database locked
```bash
# Stop the Dolt server if running
bd dolt stop
# Try again
bd list
```
### Corrupted database
```bash
# Check and fix database
bd doctor --fix
# Or pull from Dolt remote
bd dolt pull
# Or restore from a backup
bd backup restore [path] --force
```
## Dolt Server Issues
### Server not starting
```bash
# Check server health
bd doctor
# Check server logs
cat .beads/dolt/sql-server.log
# Restart the server
bd dolt stop
bd dolt start
```
### Version mismatch
After upgrading bd:
```bash
bd dolt stop
bd dolt start
```
## Sync Issues
### Changes not syncing
```bash
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
```
### Recovery from backup
```bash
# Restore from a Dolt backup
bd backup restore [path] --force
# Or pull from Dolt remote
bd dolt pull
```
### Merge conflicts
```bash
# Check for and fix Dolt conflicts
bd doctor --fix
# Re-push
bd dolt push
```
## Git Hook Issues
### Hooks not running
```bash
# Check if installed
ls -la .git/hooks/
# Reinstall
bd hooks install
```
### Hook errors
```bash
# Check hook script
cat .git/hooks/pre-commit
# Run manually
.git/hooks/pre-commit
```
## Dependency Issues
### Circular dependencies
```bash
# Detect cycles
bd dep cycles
# Remove one dependency
bd dep remove bd-A bd-B
```
### Missing dependencies
```bash
# Check orphan handling
bd config get import.orphan_handling
# Allow orphans
bd config set import.orphan_handling allow
```
## Performance Issues
### Slow queries
```bash
# Check database size
ls -lh .beads/beads.db
# Compact if large
bd admin compact --analyze
```
### High memory usage
```bash
# Reduce cache
bd config set database.cache_size 1000
```
## Getting Help
### Debug output
```bash
bd --verbose list
```
### Logs
```bash
cat .beads/dolt/sql-server.log
```
### System info
```bash
bd info --json
```
### File an issue
```bash
# Include this info
bd version
bd info --json
uname -a
```
Report at: https://github.com/gastownhall/beads/issues
</document>
---
# End of Documentation
For updates and contributions, visit: https://github.com/gastownhall/beads