6275 lines
122 KiB
Text
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
|