### Install Go Extension Binary

Source: https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md

Install the bd extension example binary using 'go install' either from the repository or local source.

```bash
# Install from the repository
go install github.com/steveyegge/beads/examples/bd-example-extension-go@latest

# Or install from local source
cd examples/bd-example-extension-go
go install .
```

--------------------------------

### Display bd Quickstart Guide

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/cli-reference/quickstart.md

Use this command to view a quick start guide that outlines common workflows and patterns for the 'bd' tool.

```bash
bd quickstart
```

--------------------------------

### Usage Examples for bd setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/cli-reference/setup.md

Common command patterns for installing, listing, and managing AI editor integrations.

```bash
bd setup cursor          # Install Cursor IDE integration
  bd setup codex           # Install Codex skill + AGENTS.md guidance + native hooks
  bd setup codex --global  # Install global Codex skill + guidance + native hooks
  bd setup copilot         # Install Copilot CLI plugin + repository instructions
  bd setup mux --project   # Install Mux workspace layer (.mux/AGENTS.md)
  bd setup mux --global    # Install Mux global layer (~/.mux/AGENTS.md)
  bd setup mux --project --global  # Install both Mux layers
  bd setup --list          # Show all available recipes
  bd setup --print         # Print the template to stdout
  bd setup -o rules.md     # Write template to custom path
  bd setup --add myeditor .myeditor/rules.md  # Add custom recipe
```

--------------------------------

### List built-in setup recipes

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/integrations/index.md

Displays all available setup recipes supported by the installed bd binary.

```bash
bd setup --list
```

--------------------------------

### bd quickstart

Source: https://github.com/gastownhall/beads/blob/main/docs/CLI_REFERENCE.md

Displays a quick start guide showing common Beads workflows and patterns.

```APIDOC
## bd quickstart

### Description
Displays a quick start guide showing common Beads workflows and patterns.

### Usage
`bd quickstart`
```

--------------------------------

### Beads Quickstart Commands

Source: https://github.com/gastownhall/beads/blob/main/docs/staged-for-removal/GETTING_STARTED_ANALYSIS.md

Install Beads using a package manager, initialize a new project, create a task, and view its status with these five simple commands.

```bash
brew install beads    # or: npm install -g @beads/bd
cd my-project
bd init               # creates database, detects role, installs hooks
bd create "My first task" -p 1
bd ready              # shows the task
```

--------------------------------

### Core Beads Commands for Getting Started

Source: https://github.com/gastownhall/beads/blob/main/docs/staged-for-removal/GETTING_STARTED_ANALYSIS.md

This sequence represents the essential commands for a new user to get started with Beads. It covers installation, project initialization, task creation, and making tasks ready.

```bash
brew install beads      # or npm install -g @beads/bd
cd your-project
bd init
bd create "Task" -p 1
bd ready
```

--------------------------------

### First-Time Setup Prompt for `bd create`

Source: https://github.com/gastownhall/beads/blob/main/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md

Example of the prompt displayed when a contributor runs `bd create` without auto-routing configured, offering options for personal tracking or direct contribution.

```text
→ Detected fork/contributor setup
→ Personal issues would pollute upstream PRs

Options:
  1. Configure auto-routing (recommended)
     Creates ~/.beads-planning for personal tracking

  2. Continue to current repo
     Issue will appear in the project database (affects PRs)

Choice [1]:
```

--------------------------------

### Example OSS Contributor Workflow

Source: https://github.com/gastownhall/beads/blob/main/examples/contributor-workflow/README.md

A comprehensive workflow example demonstrating the setup, planning, implementation, and cleanup steps for OSS contributions using beads.

```bash
# 1. Create fork and clone
git clone https://github.com/you/upstream-project.git
cd upstream-project
git remote add upstream https://github.com/upstream/upstream-project.git

# 2. Run contributor setup
bd init --contributor
# Wizard detects fork ✓
# Creates ~/.beads-planning ✓
# Configures auto-routing ✓

# 3. Plan your work (routes to planning repo)
bd create "Research how auth module works" -p 2
bd create "Design fix for bug #123" -p 1
bd ready  # Shows planning issues

# 4. Implement (commit code only)
git checkout -b fix-auth-bug
# ... make changes ...
git add . && git commit -m "Fix: auth bug"

# 5. Track discovered work (stays in planning repo)
bd create "Found related issue in logout" -p 2 --deps discovered-from:bd-abc

# 6. Push code (planning never included)
git push origin fix-auth-bug
# Create PR on GitHub - zero planning pollution!

# 7. Clean up after PR merges
bd close bd-abc --reason "PR merged"
```

--------------------------------

### Example Aider Workflow with Beads

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/integrations/aider.md

A step-by-step example demonstrating a typical workflow: checking ready work, starting Aider with issue context, creating new issues found during work, and completing/pushing changes.

```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
```

--------------------------------

### Install PyPI Build Prerequisites

Source: https://github.com/gastownhall/beads/blob/main/RELEASING.md

Install necessary build tools and verify PyPI configuration before starting the release process.

```bash
# Install build tools
pip install build twine

# Verify PyPI credentials
cat ~/.pypirc  # Should have token or credentials
```

--------------------------------

### Run Beads Library Example

Source: https://github.com/gastownhall/beads/blob/main/examples/library-usage/README.md

Commands to initialize a demo database and run the Go example program from the library's example directory.

```bash
# From this directory
cd examples/library-usage

# Make sure there's a Beads database
bd init --prefix demo

# Run the example
go run main.go
```

--------------------------------

### Install and Initialize Beads

Source: https://github.com/gastownhall/beads/blob/main/npm-package/INTEGRATION_GUIDE.md

Installs the Beads CLI globally and initializes it for the current session. Use this in session start hooks.

```bash
npm install -g @beads/bd --silent 2>&1 | grep -v "npm WARN"
bd init --quiet 2>&1 | grep -v "already initialized"
```

--------------------------------

### User installation instructions

Source: https://github.com/gastownhall/beads/blob/main/integrations/beads-mcp/PYPI.md

Standard commands for users to install the package.

```bash
pip install beads-mcp
# or with uv
uv pip install beads-mcp
```

--------------------------------

### Verify installation script

Source: https://github.com/gastownhall/beads/blob/main/RELEASING.md

Test the quick install script to ensure it correctly installs the binary.

```bash
# Test quick install script
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
bd version
```

--------------------------------

### Setup GitHub Copilot MCP Server

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/ide-setup.md

Installs the MCP server and configures VS Code for GitHub Copilot integration.

```bash
# Install MCP server
uv tool install beads-mcp
```

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```

```bash
bd init --quiet
```

--------------------------------

### Run bd quickstart

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/quickstart.md

Executes the quickstart command to display common workflows.

```bash
bd quickstart
```

--------------------------------

### Migrate Sync Example

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/migrate.md

Example for configuring the sync branch workflow.

```bash
  bd migrate sync beads-sync
```

--------------------------------

### Setup and Verify Aider Integration

Source: https://github.com/gastownhall/beads/blob/main/docs/AIDER_INTEGRATION.md

Installs the Aider integration files for Beads and then verifies the installation. This process creates configuration files for Aider to understand the Beads workflow.

```bash
# Install aider integration files
bd setup aider

# Verify installation
bd setup aider --check
```

--------------------------------

### Migrate Schema Examples

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/migrate.md

Examples for applying schema migrations.

```bash
  bd migrate schema
  bd migrate schema --json
```

--------------------------------

### Repository Configuration Example

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/repo.md

Example structure for the .beads/config.yaml file.

```yaml
repos:
    primary: "."
    additional:
      - ~/beads-planning
      - ~/work-repo
```

--------------------------------

### Install Beads Library

Source: https://github.com/gastownhall/beads/blob/main/examples/library-usage/README.md

Use 'go get' to add the latest version of the Beads library to your Go project.

```bash
go get github.com/steveyegge/beads@latest
```

--------------------------------

### Install via Script

Source: https://github.com/gastownhall/beads/blob/main/website/static/llms-full.txt

Quick installation scripts for various operating systems.

```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```

```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```

--------------------------------

### Troubleshooting Server Startup Issues

Source: https://github.com/gastownhall/beads/blob/main/docs/staged-for-removal/DOLT-BACKEND.md

Commands to diagnose and resolve server startup problems. Check for port conflicts, examine server logs, verify Dolt installation, and attempt a manual server start.

```bash
# Check if port is in use
lsof -i :3306

# Check server logs
cat .beads/dolt/sql-server.log

# Verify dolt installation
dolt version

# Try manual start
cd .beads/dolt && dolt sql-server --host 127.0.0.1 --port 3306
```

--------------------------------

### Execute bd quickstart command

Source: https://github.com/gastownhall/beads/blob/main/cmd/bd/testdata/quickstart.txt

Run the quickstart command to initialize the project structure.

```bash
bd quickstart
```

--------------------------------

### Example Workflow

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/integrations/aider.md

A complete example workflow from checking work to pushing changes.

```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
```

--------------------------------

### Install via PowerShell

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.1.0/getting-started/installation.md

Installation method for Windows environments.

```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/install.ps1 | iex
```

--------------------------------

### Full Project Workflow Example

Source: https://github.com/gastownhall/beads/blob/main/examples/multi-phase-development/README.md

A comprehensive example demonstrating issue creation, dependency management, and phase progression.

```bash
# Day 1: Planning
bd create "Build auth system" -t epic -p 1  # bd-a1b2
bd create "Phase 1: Research OAuth providers" -p 1  # bd-a1b2.1
bd create "Phase 2: Implement OAuth flow" -p 1  # bd-a1b2.2
bd create "Phase 3: Add session management" -p 2  # bd-a1b2.3
bd create "Phase 4: Security audit" -p 1  # bd-a1b2.4
bd dep add bd-a1b2.2 bd-a1b2.1 --type blocks
bd dep add bd-a1b2.3 bd-a1b2.2 --type blocks
bd dep add bd-a1b2.4 bd-a1b2.3 --type blocks

# Week 1: Phase 1 (Research)
bd ready  # Shows Phase 1 tasks
bd create "Compare Auth0 vs Firebase" -p 1 --deps discovered-from:bd-a1b2.1
bd update bd-xyz --claim
# ... research complete ...
bd close bd-a1b2.1 --reason "Chose Auth0"

# Week 2-3: Phase 2 (Implementation)
bd ready  # Now shows Phase 2 tasks
bd create "Set up Auth0 tenant" -p 1 --deps discovered-from:bd-a1b2.2
bd create "Implement login callback" -p 1 --deps discovered-from:bd-a1b2.2
bd create "Handle token refresh" -p 1 --deps discovered-from:bd-a1b2.2
# ... discovered bugs ...
bd create "Callback fails on Safari" -t bug -p 0 --deps discovered-from:bd-abc
bd close bd-a1b2.2 --reason "OAuth flow working"

# Week 4: Phase 3 (Sessions)
bd ready  # Shows Phase 3 tasks
bd create "Implement Redis session store" -p 1 --deps discovered-from:bd-a1b2.3
bd create "Add session timeout handling" -p 2 --deps discovered-from:bd-a1b2.3
bd close bd-a1b2.3 --reason "Sessions working"

# Week 5: Phase 4 (Security)
bd ready  # Shows Phase 4 tasks
bd create "Review OWASP top 10" -p 1 --deps discovered-from:bd-a1b2.4
bd create "Add CSRF protection" -p 0 --deps discovered-from:bd-a1b2.4
bd create "Pen test with security team" -p 1 --deps discovered-from:bd-a1b2.4
bd close bd-a1b2.4 --reason "Security audit passed"

# Epic complete!
bd close bd-a1b2 --reason "Auth system in production"
```

--------------------------------

### Getting Full Workflow Guide with bd prime

Source: https://github.com/gastownhall/beads/blob/main/docs/AIDER_INTEGRATION.md

Run this command to get the complete workflow guide for bd. This provides Aider with full context about bd commands.

```bash
/run bd prime
```

--------------------------------

### bd Session Start Hook Script

Source: https://github.com/gastownhall/beads/blob/main/npm-package/CLAUDE_CODE_WEB.md

A bash script to be used as a Claude Code session start hook. It ensures bd is installed globally, verifies the installation, and initializes the project if necessary.

```bash
#!/bin/bash
# .claude/hooks/session-start.sh

set -e  # Exit on error

echo "🔗 Setting up bd (beads issue tracker)..."

# Install bd globally
if ! command -v bd &> /dev/null; then
    echo "Installing @beads/bd from npm..."
    npm install -g @beads/bd --quiet
else
    echo "bd already installed"
fi

# Verify installation
if bd version &> /dev/null; then
    echo "✓ bd $(bd version)"
else
    echo "✗ bd installation failed"
    exit 1
fi

# Initialize if needed
if [ ! -d .beads ]; then
    echo "Initializing bd in project..."
    bd init --quiet
else
    echo "bd already initialized"
fi

# Show ready work
echo ""
echo "Ready work:"
bd ready --limit 5

echo ""
echo "✓ bd is ready! Use 'bd --help' for commands."
```

--------------------------------

### Command Syntax

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/cli-reference/setup.md

The basic structure for executing the setup command.

```bash
bd setup [recipe] [flags]
```

--------------------------------

### Dolt Configuration Examples

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/cli-reference/dolt.md

Examples of setting database configuration values and testing server connectivity.

```bash
bd dolt set database myproject
```

```bash
bd dolt set host 192.168.1.100 --update-config
```

```bash
bd dolt set data-dir /home/user/.beads-dolt/myproject
```

```bash
bd dolt test
```

--------------------------------

### Install via Homebrew

Source: https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md

Standard installation method for macOS and Linux users.

```bash
brew install beads
```

```bash
brew uninstall bd
brew untap gastownhall/beads 2>/dev/null || true
brew untap steveyegge/beads 2>/dev/null || true
brew install beads
```

--------------------------------

### Silent bd Installation

Source: https://github.com/gastownhall/beads/blob/main/npm-package/INTEGRATION_GUIDE.md

This bash script is intended for silent installation of bd, aiming for minimal output to keep logs clean during the setup process.

```bash
#!/bin/bash

```

--------------------------------

### Install via Go

Source: https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md

Install the binary from source using Go, selecting the appropriate build mode.

```bash
# Server-mode only
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

# Embedded-capable
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Verify Project Setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/ide-setup.md

Runs comprehensive health checks on the beads installation.

```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
```

--------------------------------

### Initial Setup and Status Check

Source: https://github.com/gastownhall/beads/blob/main/examples/linear-workflow/README.md

Demonstrates the initial setup for Beads, setting the Linear API key and team ID, and then checking the sync status.

```bash
# Initial setup
$ bd init --quiet
$ export LINEAR_API_KEY="lin_api_abc123..."  # add to ~/.secrets or ~/.zshrc
$ bd config set linear.team_id "team-uuid-456"

# Check status
$ bd linear status
Linear Sync Status
==================

Team ID:      team-uuid-456
API Key:      lin_...c123
Last Sync:    Never

Total Issues: 0
With Linear:  0
Local Only:   0
```

--------------------------------

### Zsh completion setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/completion.md

Commands to generate and install zsh autocompletion scripts.

```zsh
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

```zsh
source <(bd completion zsh)
```

```zsh
bd completion zsh > "${fpath[1]}/_bd"
```

```zsh
bd completion zsh > $(brew --prefix)/share/zsh/site-functions/_bd
```

```zsh
bd completion zsh [flags]
```

```bash
--no-descriptions   disable completion descriptions
```

--------------------------------

### PowerShell completion setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/completion.md

Commands to generate and install PowerShell autocompletion scripts.

```powershell
bd completion powershell | Out-String | Invoke-Expression
```

```powershell
bd completion powershell [flags]
```

```bash
--no-descriptions   disable completion descriptions
```

--------------------------------

### Fish completion setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/completion.md

Commands to generate and install fish autocompletion scripts.

```fish
bd completion fish | source
```

```fish
bd completion fish > ~/.config/fish/completions/bd.fish
```

```fish
bd completion fish [flags]
```

```bash
--no-descriptions   disable completion descriptions
```

--------------------------------

### Example Workflow: Molecule Creation and Progression

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/workflows/molecules.md

A step-by-step example demonstrating the creation of a molecule from a formula, viewing its structure, and progressing through its steps until completion.

```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
```

--------------------------------

### Initialize Beads Project

Source: https://github.com/gastownhall/beads/blob/main/examples/multi-phase-development/README.md

Set up the beads environment and optionally start the Dolt server for synchronization.

```bash
# Initialize beads in your project
cd my-project
bd init

# Start Dolt server for auto-sync (optional)
bd dolt start
```

--------------------------------

### Bash completion setup

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/completion.md

Commands to generate and install bash autocompletion scripts.

```bash
source <(bd completion bash)
```

```bash
bd completion bash > /etc/bash_completion.d/bd
```

```bash
bd completion bash > $(brew --prefix)/etc/bash_completion.d/bd
```

```bash
bd completion bash
```

```bash
--no-descriptions   disable completion descriptions
```

--------------------------------

### Install bd via SessionStart Hook

Source: https://github.com/gastownhall/beads/blob/main/npm-package/CLAUDE_CODE_WEB.md

Automates the installation of the bd npm package globally and initializes it in the project. This is the recommended setup for Claude Code for Web sessions.

```bash
#!/bin/bash
# .claude/hooks/session-start.sh

# Install bd globally (only takes a few seconds)
echo "Installing bd (beads issue tracker)..."
npm install -g @beads/bd

# Initialize bd in the project (if not already initialized)
if [ ! -d .beads ]; then
  bd init --quiet
fi

echo "✓ bd is ready! Use 'bd ready' to see available work."
```

--------------------------------

### Run bd Example Extension Demo

Source: https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md

Executes the bd-example-extension-go with the 'demo' command. This command likely triggers a predefined workflow or test scenario.

```bash
bd-example-extension-go -cmd demo
```

--------------------------------

### Install Dolt for Central Server Setup

Source: https://github.com/gastownhall/beads/blob/main/docs/staged-for-removal/DOLT-BACKEND.md

Installs Dolt using Homebrew, a prerequisite for setting up a central persistent Dolt server for managing multiple Beads projects.

```bash
brew install dolt
```

--------------------------------

### Start and Initialize Server Mode

Source: https://github.com/gastownhall/beads/blob/main/docs/DOLT.md

Commands to start the Dolt SQL server and initialize a project in server mode.

```bash
# Start the server (orchestrator)
gt dolt start

# Or manually
cd ~/.dolt-data/beads && dolt sql-server --port 3307
```

```bash
# Initialize in server mode
bd init --server

# Or switch via environment variable
export BEADS_DOLT_SERVER_MODE=1
```

--------------------------------

### Best Practices for CLI Usage

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.1.0/integrations/junie.md

Examples demonstrating recommended CLI usage patterns.

```bash
bd list --json          # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json    # Structured data
```

```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
```

```bash
# When you discover issues during work
bd create "Found related bug" \
  --deps discovered-from:bd-current --json
```

```bash
# ALWAYS run before ending
bd dolt push
```

--------------------------------

### Setup Claude Code Integration

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/ide-setup.md

Configures the Claude Code integration and verifies the installation.

```bash
# Setup Claude Code integration
bd setup claude
```

```bash
bd setup claude --check
```

--------------------------------

### Quick Setup for Claude Code

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/integrations/claude-code.md

Installs necessary hooks for session management and context refreshing.

```bash
bd setup claude
```

--------------------------------

### Initialize a project

Source: https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md

Navigate to the project directory and initialize the Beads environment.

```bash
cd your-project && bd init
```

--------------------------------

### Initialize and build the project

Source: https://github.com/gastownhall/beads/blob/main/CONTRIBUTING.md

Commands to clone the repository and build the project using the Makefile.

```bash
# Clone the repository
git clone https://github.com/gastownhall/beads
cd beads

# Build the project (uses gms_pure_go tag via Makefile)
make build

# Run tests (uses correct build tags automatically)
make test

# Build and install locally to ~/.local/bin
make install
```

--------------------------------

### Library Installation Blocks Dependency

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/resources/DEPENDENCIES.md

Use 'blocks' when a task, like implementing code, cannot start because a prerequisite, such as installing a library, is not yet complete. This dependency prevents the dependent task from appearing in 'bd ready'.

```yaml
setup-1: "Install JWT library"
  blocks
auth-2: "Implement JWT validation"

Why: Code won't compile/run without library
Effect: Can't start auth-2 until setup-1 complete
```

--------------------------------

### Initialize and Install Beads

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md

Commands for setting up the environment and initializing a new project.

```bash
npm install -g @beads/cli
```

```bash
bd init <prefix>
```

--------------------------------

### Setup MCP Server for Claude Desktop

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/ide-setup.md

Installs the MCP server and configures it for Claude Desktop environments.

```bash
# Install MCP server
pip install beads-mcp
```

```json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

--------------------------------

### Install via Go on Windows

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/installation.md

Direct installation using Go on Windows with environment variable configuration.

```pwsh
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
```

```pwsh
$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Jira sync command examples

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/jira.md

Examples for running the sync command with various flags.

```bash
bd jira sync --pull                # Import from Jira
bd jira sync --push --create-only  # Push new issues only
bd jira sync --dry-run             # Preview without changes
bd jira sync --prefer-local        # Bidirectional, local wins
```

--------------------------------

### Setup Junie Integration

Source: https://github.com/gastownhall/beads/blob/main/integrations/junie/README.md

Installs the Junie integration for beads. This sets up necessary configuration files for Junie to interact with beads.

```bash
bd setup junie
```

--------------------------------

### Verify bd quickstart output

Source: https://github.com/gastownhall/beads/blob/main/cmd/bd/testdata/quickstart.txt

Expected output strings after running the quickstart command.

```text
stdout 'Dependency-Aware'
stdout 'bd init'
stdout 'bd create'
```

--------------------------------

### Setup Codex Integration

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/integrations/codex.md

Run these commands to set up the Beads integration with Codex. Use the --check flag to verify the installation.

```bash
bd setup codex
```

```bash
bd setup codex --check
```

--------------------------------

### Check beads-mcp installation

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/integrations/mcp-server.md

Verify that the 'beads-mcp' command is accessible in your system's PATH. This is a troubleshooting step if the server won't start.

```bash
which beads-mcp
```

--------------------------------

### Using bd via npm Scripts or npx

Source: https://github.com/gastownhall/beads/blob/main/npm-package/CLAUDE_CODE_WEB.md

Examples of how to execute bd commands when it is installed as a project dependency, using either `npm run` or `npx`.

```bash
npm run ready
npx bd create "New issue"
```

--------------------------------

### Initialize Team Workflow

Source: https://github.com/gastownhall/beads/blob/main/examples/team-workflow/README.md

Run the setup wizard within a shared repository to enable team collaboration features.

```bash
# In your shared repository
cd my-project

# Run the team setup wizard
bd init --team
```

--------------------------------

### Check CLI Help

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/quickstart.md

Verifies the installation by displaying the help menu.

```bash
bd --help
```

--------------------------------

### Setup Gemini CLI Integration

Source: https://github.com/gastownhall/beads/blob/main/website/static/llms-full.txt

Configures Beads hooks and guidance for Gemini CLI. Supports global or project-local installation and stealth mode for CI environments.

```bash
bd setup gemini
bd setup gemini --check
```

```bash
bd setup gemini --project
```

```bash
bd setup gemini --stealth
bd setup gemini --project --stealth
```

```bash
bd setup gemini --remove
bd setup gemini --project --remove
```

--------------------------------

### Get SHA256 checksum for Windows release

Source: https://github.com/gastownhall/beads/blob/main/winget/README.md

This command fetches the checksums file from the GitHub releases and filters for the Windows checksum, which is required when updating the installer manifest.

```bash
curl -sL https://github.com/gastownhall/beads/releases/download/v<VERSION>/checksums.txt | grep windows
```

--------------------------------

### Implement Custom Benchmark

Source: https://github.com/gastownhall/beads/blob/main/BENCHMARKS.md

Manually manage setup, cleanup, and timer reporting for custom benchmark scenarios.

```go
func BenchmarkMyTest(b *testing.B) {
	store, cleanup := setupLargeBenchDB(b)
	defer cleanup()
	ctx := context.Background()

	b.ResetTimer()
	b.ReportAllocs()

	for i := 0; i < b.N; i++ {
		// Your test code here
	}
}
```

--------------------------------

### Source bd-version-check.sh Script

Source: https://github.com/gastownhall/beads/blob/main/examples/startup-hooks/README.md

Source this script at session start for automatic bd upgrade detection and notifications. Ensure bd and jq are installed and a .beads directory exists.

```bash
source examples/startup-hooks/bd-version-check.sh
```

--------------------------------

### Claude Code Prompt for bd Usage

Source: https://github.com/gastownhall/beads/blob/main/npm-package/CLAUDE_CODE_WEB.md

An example prompt for Claude Code demonstrating the workflow for using bd for issue tracking, including starting, updating, and closing issues.

```text
You are working on a project that uses bd (beads) for issue tracking.

At the start of each session:
1. Run `bd ready --json` to see available work
2. Choose an issue to work on
3. Start work: `bd update <id> --claim`

While working:
- Create new issues for any bugs you discover
- Link related issues with `bd dep add`
- Add comments with `bd comments add <id> "comment text"`

When done:
- Close the issue: `bd close <id> --reason "Description of what was done"`
- Run `bd dolt push` to push issue changes
```

--------------------------------

### Typical Sync Workflow

Source: https://github.com/gastownhall/beads/blob/main/docs/SYNC_SETUP.md

Example sequence of commands demonstrating task creation, synchronization, and state updates across two machines.

```text
Machine A                          Machine B
─────────                          ─────────
bd create "New task" -p 1
bd dolt push
                                   bd dolt pull
                                   bd update bd-a1b2 --claim
                                   bd close bd-a1b2 --reason "Done"
                                   bd dolt push
bd dolt pull
bd list                            # sees the closed task
```

--------------------------------

### Setup Claude Code for Web Session Hook

Source: https://github.com/gastownhall/beads/blob/main/npm-package/TESTING.md

Install Beads CLI globally and initialize it for use within a Claude Code for Web session. Ensure the script is executable.

```bash
#!/bin/bash
npm install -g @beads/bd
bd init --quiet
```

```bash
chmod +x .claude/hooks/session-start.sh
```

```bash
bd version
bd list
```

--------------------------------

### Example: Create and View Custom Template

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/commands/template.md

Shows the process of creating a custom 'performance' template and its default YAML structure.

```bash
$ bd template create performance
✓ Created template: .beads/templates/performance.yaml
Edit the file to customize your template.

$ cat .beads/templates/performance.yaml
name: performance
description: |-
    [Describe the issue]
    
    ## Additional Context
    
    [Add relevant details]
type: task
priority: 2
labels: []
design: '[Design notes]'
acceptance_criteria: |-
    - [ ] Acceptance criterion 1
    - [ ] Acceptance criterion 2

# Edit the template to customize it
$ vim .beads/templates/performance.yaml

```

--------------------------------

### List All Configuration

Source: https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md

Displays all current configuration settings in either plain text or JSON format.

```bash
bd config list
bd config list --json  # JSON output
```

```text
Configuration:
  compact_tier1_days = 90
  compact_tier1_dep_levels = 2
  jira.project = PROJ
  jira.url = https://company.atlassian.net
```

```json
{
  "compact_tier1_days": "90",
  "compact_tier1_dep_levels": "2",
  "jira.project": "PROJ",
  "jira.url": "https://company.atlassian.net"
}
```

--------------------------------

### Setup Claude Code Integration

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/getting-started/ide-setup.md

Run this command to set up the SessionStart hook and compact refresh for Claude Code integration. This automatically runs `bd prime` on session start and after context compaction.

```bash
bd setup claude
```

--------------------------------

### Full Workflow Example: Implement OAuth Authentication

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md

Demonstrates a multi-session workflow for implementing a feature, showing how to create, update, and use both Beads and TodoWrite to manage tasks and capture outcomes.

```bash
# Create bd issue
bd create "Implement OAuth authentication" -t feature -p 0 --design "
JWT tokens with refresh rotation.
See BOUNDARIES.md for bd vs TodoWrite decision.
"

# Mark in_progress
bd update oauth-1 --claim

# Create TodoWrite for today's work
TodoWrite:
- [ ] Research OAuth 2.0 refresh token flow
- [ ] Design token schema
- [ ] Set up test environment
```

```bash
# Update bd with outcomes
bd update oauth-1 --notes "COMPLETED: Researched OAuth2 refresh flow. Decided on 7-day refresh tokens.
KEY DECISION: RS256 over HS256 (enables key rotation per security review).
IN PROGRESS: Need to set up test OAuth provider.
NEXT: Configure test provider, then implement token endpoint."

# TodoWrite disappears when session ends
```

```bash
# Read bd to reconstruct context
bd show oauth-1
# See: COMPLETED research, NEXT is configure test provider

# Create fresh TodoWrite from NEXT
TodoWrite:
- [ ] Configure test OAuth provider
- [ ] Implement token endpoint
- [ ] Add basic tests

# Work proceeds...

# Update bd at milestone
bd update oauth-1 --notes "COMPLETED: Test provider configured, token endpoint implemented.
TESTS: 5 passing (token generation, validation, expiry).
IN PROGRESS: Adding refresh token rotation.
NEXT: Implement rotation, add rate limiting, security review."
```

--------------------------------

### Install via Go

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/installation.md

Direct installation using Go, supporting server-mode and embedded-capable configurations.

```bash
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
```

```bash
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### OAuth Integration Setup with Beads

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/resources/WORKFLOWS.md

Example of setting up an 'OAuth integration' epic using `bd` commands. Includes creating issues, adding dependencies with `bd dep add`, and verifying with `bd blocked`.

```bash
# Create epic (the goal)
bd create "OAuth integration" -t epic

# Walk backward: What does OAuth need?
bd create "Login/logout endpoints" -t task        # needs token storage
bd create "Token storage and refresh" -t task     # needs auth flow
bd create "Authorization code flow" -t task       # needs credentials
bd create "OAuth client credentials" -t task      # foundation

# Add deps using requirement language: "X needs Y"
bd dep add endpoints storage      # endpoints need storage
bd dep add storage flow           # storage needs flow
bd dep add flow credentials       # flow needs credentials
# credentials has no deps - it's Ready Front 1

# Verify: bd blocked should show sensible blocking
bd blocked
# endpoints blocked by storage ✓
# storage blocked by flow ✓
# flow blocked by credentials ✓
# credentials ready ✓
```

--------------------------------

### Multi-Session Resume Workflow

Source: https://github.com/gastownhall/beads/blob/main/plugins/beads/skills/beads/resources/WORKFLOWS.md

This workflow is designed for resuming work after significant breaks. It leverages Beads commands to quickly get an overview of available work, project status, and recent activity, ensuring you start with full context.

```markdown
Resume Workflow:
- [ ] Run bd ready to see available work
- [ ] Run bd stats for project overview
- [ ] List recent closed issues for context
- [ ] Show details on issue to work on
- [ ] Review design notes and acceptance criteria
- [ ] Claim issue (`bd update <id> --claim`)
- [ ] Begin work with full context
```

--------------------------------

### Install and Initialize Beads

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/intro.md

Install Beads via Homebrew or a script, then initialize it in your project directory.

```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
```

--------------------------------

### Manually Install Beads CLI

Source: https://github.com/gastownhall/beads/blob/main/npm-package/INTEGRATION_GUIDE.md

Installs the Beads CLI globally if the automatic installation fails. Verify the installation afterward.

```bash
# Manually install
npm install -g @beads/bd

# Verify
bd version
```

--------------------------------

### Install Beads on Windows via PowerShell

Source: https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md

Use the PowerShell installation script to install a prebuilt Windows release.

```pwsh
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
```

--------------------------------

### Install Beads Git Hooks

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/cli-reference/hooks.md

Installs git hooks for Beads integration. By default, hooks are installed to .git/hooks/. Use the --beads flag to install to .beads/hooks/ or --shared to install to a versioned directory (.beads-hooks/) for team sharing. Existing hooks are preserved using section markers.

```bash
bd hooks install [flags]
```

--------------------------------

### Implement Standard Benchmark

Source: https://github.com/gastownhall/beads/blob/main/BENCHMARKS.md

Use the runBenchmark helper to execute a test case with standard setup.

```go
// BenchmarkMyTest benchmarks a specific operation
func BenchmarkMyTest(b *testing.B) {
	runBenchmark(b, setupLargeBenchDB, func(store *SQLiteStorage, ctx context.Context) error {
		// Your test code here
		return err
	})
}
```

--------------------------------

### Optimize npm Installation

Source: https://github.com/gastownhall/beads/blob/main/npm-package/INTEGRATION_GUIDE.md

Optimizes the npm installation process for Beads by configuring the npm cache or installing it as a development dependency.

```bash
# Use npm cache
npm config set cache ~/.npm-cache

# Or install as dependency (cached by package-lock.json)
npm install --save-dev @beads/bd
```

--------------------------------

### Install Aider Integration

Source: https://github.com/gastownhall/beads/blob/main/docs/SETUP.md

Initializes the Aider configuration and instruction files.

```bash
bd setup aider
```

--------------------------------

### Install Dolt on macOS and Linux

Source: https://github.com/gastownhall/beads/blob/main/docs/staged-for-removal/DOLT-BACKEND.md

Installs the Dolt version control system for databases. Verify the installation by checking the version.

```bash
# macOS
brew install dolt

# Linux
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash

# Verify installation
dolt version
```

--------------------------------

### Agent project workflow

Source: https://github.com/gastownhall/beads/blob/main/docs/FAQ.md

Automated initialization steps for agents setting up repositories.

```bash
git clone <repo>
cd <repo>
bd init --quiet  # No prompts, auto-installs hooks
bd ready --json  # Start using bd normally
```

--------------------------------

### Global Installation of Beads CLI

Source: https://github.com/gastownhall/beads/blob/main/npm-package/TESTING.md

Install the Beads CLI globally for system-wide access. Verify the installation and use it in any project directory.

```bash
# Install globally
npm install -g @beads/bd

# Verify
which bd
bd version

# Use in any project
mkdir ~/projects/test
cd ~/projects/test
git init
bd init
bd create "First issue" -p 1
bd list
```

--------------------------------

### Install Beads via Go (Server Mode)

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.1.0/getting-started/installation.md

Install the server-mode binary using Go with CGO disabled.

```bash
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
```

```pwsh
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Install @beads/bd Package

Source: https://github.com/gastownhall/beads/blob/main/npm-package/LAUNCH.md

Install the @beads/bd package globally for command-line use or as a project dependency. Verify the installation by checking the version.

```bash
npm install -g @beads/bd
```

```bash
npm install --save-dev @beads/bd
```

```bash
bd version
```

--------------------------------

### Upgrade bd using go install (server-mode)

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/getting-started/upgrading.md

Install or upgrade bd using 'go install' for server-mode, ensuring CGO is disabled.

```bash
# Server-mode only
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Build from Source

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/getting-started/installation.md

Manual build process for macOS environments.

```bash
git clone https://github.com/gastownhall/beads
cd beads
make build
sudo mv bd /usr/local/bin/
```

--------------------------------

### Build and Test Locally

Source: https://github.com/gastownhall/beads/blob/main/CONTRIBUTING.md

Commands to install the project and verify functionality using the CLI.

```bash
# Build and install your changes
make install

# Test specific functionality
bd init --prefix test
bd create "Test issue" -p 1 -t bug
bd dep add test-2 test-1
bd ready
```

--------------------------------

### Setup Mux Integration

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/integrations/mux.md

Initializes Mux integration in the root AGENTS.md file.

```bash
bd setup mux
bd setup mux --check
```

--------------------------------

### Offline/Cached Installation of Beads CLI

Source: https://github.com/gastownhall/beads/blob/main/npm-package/TESTING.md

Demonstrates installing, uninstalling, and reinstalling the Beads CLI to leverage npm's cache for faster subsequent installations.

```bash
# First install (downloads binary)
npm install -g @beads/bd

# Uninstall
npm uninstall -g @beads/bd

# Reinstall (should use npm cache)
npm install -g @beads/bd
# Should be faster (no binary download if cached)
```

--------------------------------

### Configure agent integrations

Source: https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md

List available integrations or perform manual onboarding.

```bash
bd setup --list
```

```bash
bd onboard
```

--------------------------------

### Check Git Hook Installation

Source: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.4/reference/troubleshooting.md

Verify that Git hooks are installed by listing the contents of the .git/hooks directory. If they are missing, reinstall them using 'bd hooks install'.

```bash
ls -la .git/hooks/

bd hooks install
```