### Quick Install by Building from Source

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Clones the repository, builds the release binary, and installs it system-wide. Useful for development or customization.

```bash
git clone https://github.com/Dicklesworthstone/beads_rust.git && cd beads_rust && cargo build --release && sudo cp target/release/br /usr/local/bin/
```

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

### Beads CLI 'init' Command Output Examples

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Provides example output for the 'bd init' command in both text and JSON formats.

```text
- Text: `Initialized beads workspace in .beads/`
- JSON: `{"status": "initialized", "path": ".beads/", "prefix": "bd"}`
```

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

### Beads Agent Workflow Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

Example bash commands demonstrating a typical AI agent workflow: getting the top priority task, claiming work, performing the task, closing it, and performing a final export check.

```bash
# Agent workflow
br ready --json | jq '.[0]'           # Get top priority
```

```bash
br update br-abc --status in_progress # Claim work
```

```bash
# ... do work ...
br close br-abc --reason "Completed"  # Done; JSONL auto-flushes by default
```

```bash
br sync --flush-only                  # Final export check before staging .beads/
```

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

### Example Configuration File

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

This is an example of a `.beads/config.yaml` file, showing settings for issue ID prefix, default values, output formatting, and sync behavior.

```yaml
# .beads/config.yaml

# Default issue ID prefix for newly created issues
id:
  prefix: "proj"

# Default values for new issues
defaults:
  priority: 2
  type: "task"
  assignee: "team@example.com"

# Output formatting
output:
  color: true
  date_format: "%Y-%m-%d"

# Sync behavior
sync:
  auto_import: false
  auto_flush: false

```

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

### Install and run MCP server (global)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/AGENT_INTEGRATION.md

Commands to install the `br` binary globally with the `mcp` feature and then run the MCP server, logging errors.

```bash
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git --features mcp
RUST_LOG=error br serve --actor codex
```

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

### Download and Install Pre-built Binary (Linux)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Downloads a pre-built release binary for Linux x86_64 from GitHub Releases, extracts it, and installs it to `/usr/local/bin/`.

```bash
# Example for Linux x86_64
VERSION=v0.1.23
curl -L "https://github.com/Dicklesworthstone/beads_rust/releases/download/${VERSION}/br-${VERSION}-linux_amd64.tar.gz" -o br.tar.gz
tar -xzf br.tar.gz br
sudo install -m 0755 br /usr/local/bin/br
```

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

### Install Rust and br on Windows with PowerShell

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs Rust using rustup via a downloaded executable and then installs the 'br' tool from its Git repository. Requires restarting PowerShell after Rust installation.

```powershell
# Install Rust via rustup
Invoke-WebRequest -Uri https://win.rustup.rs/x86_64 -OutFile rustup-init.exe
.
ustup-init.exe

# Restart PowerShell, then:
rustup install nightly
rustup default nightly

# Install br
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Install br CLI from Source

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

Builds and installs the br CLI from its source code. Requires Rust nightly. Includes options for local build and global installation.

```bash
# Requires Rust nightly
git clone https://github.com/Dicklesworthstone/beads_rust.git
cd beads_rust
cargo build --release
./target/release/br --help
```

```bash
# Or install globally
cargo install --path .
```

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

### Install Rust and br on macOS

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs Rust using rustup and then installs the 'br' tool from its Git repository. Ensure you have curl installed.

```bash
# Install Rust via rustup (recommended over Homebrew Rust)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install nightly
rustup install nightly
rustup default nightly

# Install br
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Download and Install Pre-built Binary (macOS)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Downloads a pre-built release binary for macOS ARM64 from GitHub Releases, extracts it, and installs it to `/usr/local/bin/`.

```bash
# Example for macOS ARM64
VERSION=v0.1.23
curl -L "https://github.com/Dicklesworthstone/beads_rust/releases/download/${VERSION}/br-${VERSION}-darwin_arm64.tar.gz" -o br.tar.gz
tar -xzf br.tar.gz br
sudo install -m 0755 br /usr/local/bin/br
```

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

### Install br CLI

Source: https://context7.com/dicklesworthstone/beads_rust/llms.txt

Installs the br CLI tool using a curl script. Verifies the installation by checking the version.

```bash
# Auto-detects platform (Linux, macOS, Windows WSL) and downloads the right binary
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash

# Verify
br --version
# br 0.2.6
```

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

### Correct Cargo install command

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Demonstrates the correct command to install 'br' directly from its Git repository, contrasting it with an incorrect local build attempt.

```bash
# Correct: install from git
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git

# Wrong: trying to build without cloning first
cargo build  # This requires Cargo.toml in current directory
```

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

### Environment Variable Configuration Examples

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Examples of setting configuration options using environment variables with the BD_ prefix. These override config files and DB settings.

```bash
BD_NO_DAEMON=true
BD_ISSUE_PREFIX=proj
BD_SYNC_REQUIRE_CONFIRMATION_ON_MASS_DELETE=true
```

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

### Install beads_rust with Cargo (Recommended)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs beads_rust using Cargo. Use `--no-default-features` to exclude the self-update feature.

```bash
# Install with all features (including self-update)
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git

# Install without self-update feature
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git --no-default-features
```

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

### Quick Install using Cargo

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs beads_rust directly from its Git repository using Cargo. Requires Rust nightly toolchain.

```bash
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Initialize Agent Repository

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/agent/QUICKSTART.md

Run this command once per repository to initialize the agent setup.

```bash
br init
```

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

### Get Help for Create Command

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TROUBLESHOOTING.md

Check the help documentation for the 'create' command to see required fields.

```bash
br create --help
```

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

### Run Cold/Warm Start Benchmarks

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TEST_HARNESS.md

Execute cold and warm start benchmarks. Use HARNESS_ARTIFACTS=1 to capture detailed artifacts. Specific tests like startup_matrix_smoke_bundle and perf_evidence_smoke_bundle can be targeted.

```bash
cargo test --test bench_cold_warm_start -- --nocapture --ignored
HARNESS_ARTIFACTS=1 cargo test --test bench_cold_warm_start -- --nocapture --ignored
cargo test --test bench_cold_warm_start startup_matrix_smoke_bundle -- --nocapture
cargo test --test bench_cold_warm_start perf_evidence_smoke_bundle -- --nocapture
```

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

### Install br with curl

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/agent_baseline/README_first_80_lines.md

Installs br by downloading the latest release script. It auto-detects your platform and fetches the correct binary for Linux, macOS, and Windows (WSL).

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash
```

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

### Verify br installation and basic commands

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Checks the installed version of 'br', displays help information, and runs a sequence of basic commands to confirm functionality.

```bash
# Check version
br version

# Expected output:
# br 0.1.0 (abc1234)
# Built: 2026-01-17

# Check help
br --help

# Run a simple command
br init
br create "Test issue" --type task
br list
br delete bd-xxx  # Clean up test issue
```

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

### Check Git Installation

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/E2E_SYNC_TESTS.md

Verify that Git is installed and available in the system's PATH. Some tests rely on Git for verifying safety invariants.

```bash
# Check git is available
git --version

# Install if missing (Ubuntu/Debian)
sudo apt-get install git
```

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

### Install br to user directory

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Provides two options for handling 'permission denied' errors when installing 'br': using sudo to copy to a system-wide location or copying to a user-specific bin directory and adding it to the PATH.

```bash
# Option 1: Use sudo
sudo cp target/release/br /usr/local/bin/

# Option 2: Install to user directory
mkdir -p ~/.local/bin
cp target/release/br ~/.local/bin/
# Add to PATH if needed:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

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

### Install Rust Nightly Toolchain

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs Rustup and the nightly toolchain, setting it as the default. Alternatively, use `rustup run nightly` for a single command.

```bash
# Install rustup if not present
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install and set nightly as default
rustup install nightly
rustup default nightly

# Or use nightly for just this install
rustup run nightly cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Dependency Tree Output - Text Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Example of the text-based output format for the 'bd dep tree' command, illustrating hierarchical issue dependencies.

```text
bd-epic-1 [Epic: User Management]
├── bd-task-1 [P1] Design schema
│   ├── bd-task-2 [P2] Implement models
│   │   └── bd-task-3 [P2] Write tests
│   └── bd-task-4 [P2] API endpoints
└── bd-task-5 [P1] Documentation
```

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

### Start MCP Server

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/CLI_REFERENCE.md

Start an MCP (Model Context Protocol) server on stdio. This command is only available in binaries built with the optional 'mcp' feature. Use when an MCP-native agent benefits from tool/resource discovery and structured recovery hints.

```bash
br serve [OPTIONS]
```

```bash
cargo build --release --features mcp
```

```bash
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git --features mcp
```

```json
{
  "mcpServers": {
    "br": {
      "command": "br",
      "args": ["serve", "--actor", "codex"],
      "env": {
        "RUST_LOG": "error"
      }
    }
  }
}
```

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

### Project Statistics Output - Text Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Example text output from the 'bd stats' command, showing total issue counts, status distributions, and breakdowns by priority.

```text
Issue Statistics
================

Total:        142
Open:          45  (31.7%)
In Progress:   12  (8.5%)
Closed:        78  (54.9%)
Blocked:        5  (3.5%)
Deferred:       2  (1.4%)

Ready to work: 38
Avg lead time: 4.2 days

By Priority:
  P0:  3 issues
  P1: 15 issues
  P2: 67 issues
  P3: 42 issues
  P4: 15 issues

```

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

### Example JSON Output for 'br ready'

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/AGENT_INTEGRATION.md

An example of the JSON output produced by the `br ready --json --limit 2` command, showing the structure for a list of issues with details like ID, title, status, priority, and assignee.

```json
[
  {
    "id": "br-abc123",
    "title": "Implement user auth",
    "status": "open",
    "priority": 1,
    "issue_type": "feature",
    "assignee": "",
    "dependency_count": 0,
    "dependent_count": 2
  },
  {
    "id": "br-def456",
    "title": "Fix login bug",
    "status": "open",
    "priority": 0,
    "issue_type": "bug",
    "assignee": "alice",
    "dependency_count": 1,
    "dependent_count": 0
  }
]
```

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

### Install Rust and br in WSL2 (Ubuntu)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs necessary build tools, Rust via rustup, and the 'br' tool from its Git repository within a WSL2 Ubuntu environment. Ensure you update package lists first.

```bash
# In WSL2 (Ubuntu)
sudo apt update && sudo apt install -y build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup install nightly
rustup default nightly
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Get Machine-Readable Command Contracts with `br capabilities`

Source: https://context7.com/dicklesworthstone/beads_rust/llms.txt

Use `br capabilities` to get a structured description of all commands, flags, output formats, exit codes, and safety guarantees. This is recommended for agents bootstrapping in an unknown `br` installation. Output can be in JSON format.

```bash
br capabilities --format json
```

```bash
br capabilities --format json --command "create"
```

```bash
br capabilities --format json --command "comments add"
```

```bash
br capabilities --format json --command "dep add"
```

```bash
br capabilities --format json --command "update"
```

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

### Example Session Before

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/plans/RICH_INTEGRATION_PLAN.md

Illustrates the current output format for the `ready` and `show` commands before migration to rich text. This serves as a baseline for comparison.

```text
$ br ready
bd-d4e5f6  1  Feature  Add OAuth2 support
bd-j1k2l3  2  Task     Refactor storage layer

$ br show bd-d4e5f6
ID: bd-d4e5f6
Title: Add OAuth2 support
Status: Open
Priority: 1
Type: Feature
Assignee:
Created: 2024-01-15T14:30:00Z
```

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

### Get Dependency Tree Structure

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Builds a tree structure of dependencies starting from a root issue. Allows limiting recursion depth and returns a nested structure suitable for rendering.

```go
// GetDependencyTree builds a tree structure of dependencies
// - maxDepth limits recursion (default 10)
// - Returns nested structure suitable for tree rendering
GetDependencyTree(ctx context.Context, rootID string, maxDepth int) (*types.DependencyNode, error)
```

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

### Parse beads JSON output with jq

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/AGENTS.md

jq can be used to parse the JSON output from beads commands for specific information. Examples include getting a summary, top recommendations, or details about cycles.

```bash
bv --robot-triage | jq '.quick_ref'
```

```bash
bv --robot-triage | jq '.recommendations[0]'
```

```bash
bv --robot-plan | jq '.plan.summary.highest_impact'
```

```bash
bv --robot-insights | jq '.status'
```

```bash
bv --robot-insights | jq '.Cycles'
```

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

### Rich Output Example: `br init`

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/plans/RICH_INTEGRATION_PLAN.md

Demonstrates the rich output format for the `br init` command, showing a success message and workspace details within a styled panel.

```text
╭────────────────────────────────────────────────────╮
│  ✓ Initialized beads workspace                     │
│                                                    │
│  Location: /path/to/project/.beads                 │
│  Database: beads.db                                │
│  Export:   issues.jsonl                            │
│                                                    │
│  Next steps:                                       │
│    br create "Your first issue" --type task        │
│    br list                                         │
╰────────────────────────────────────────────────────╯
```

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

### Full Dependency Workflow Example

Source: https://context7.com/dicklesworthstone/beads_rust/llms.txt

Demonstrates a complete workflow for managing dependencies, including creating issues, adding dependencies, and identifying the next ready issue.

```bash
# Full dependency workflow example
br create "Deploy to production" --type task --priority 0
# Created: br-deploy1
br create "Run full test suite" --type task --priority 1
# Created: br-tests1
br create "Update database migrations" --type task --priority 1
# Created: br-db1

br dep add br-deploy1 br-tests1   # deploy blocked by tests
br dep add br-deploy1 br-db1      # deploy blocked by db migration
br dep add br-tests1 br-db1       # tests blocked by db migration

br ready
# br-db1  P1  task  Update database migrations  (only this is unblocked)
```

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

### Get In-Tool Agent Documentation with `br robot-docs`

Source: https://context7.com/dicklesworthstone/beads_rust/llms.txt

Use `br robot-docs` to print a concise handbook for automation agents directly within the tool. Options include a text-based guide or structured JSON output containing contract version and canonical commands.

```bash
br robot-docs guide
```

```bash
br robot-docs guide --format json
```

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

### Template Instantiation Command Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Demonstrates how to instantiate a template with variables and an assignee. Use --dry-run to preview changes without creating issues.

```bash
bd template instantiate <template-id> [--var key=value ...] [--assignee name] [--dry-run]
```

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

### Initialize Project

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/CLI_REFERENCE.md

Use `br init` to initialize a new project with a custom prefix or to force reinitialization.

```bash
br init --prefix myproj
```

```bash
br init --force
```

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

### Quick Start: Running Test Suites

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TEST_HARNESS.md

Execute quick E2E tests for fast feedback or run the full test suite. Conformance tests require the bd binary, and benchmarks offer performance comparisons.

```bash
scripts/e2e.sh                    # Quick E2E subset (~6 tests)

E2E_FULL_CONFIRM=1 scripts/e2e_full.sh   # All E2E tests

scripts/conformance.sh            # br vs bd parity checks

scripts/bench.sh --quick          # Quick performance comparison
```

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

### Verify br Installation

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

Checks the installed version of the br CLI. This command should be run after installation to confirm it is working correctly.

```bash
br --version
# br 0.1.45
```

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

### Swarm Capacity-Planning Report Setup

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TEST_HARNESS.md

Sets up the directory structure and copies necessary input files for generating a swarm capacity-planning report. Executes Beads commands to gather data.

```bash
export BR_CAPACITY_REPORT_DIR=tests/artifacts/perf/beads-perf-<timestamp>-swarm-capacity-planning
export BR_CAPACITY_WORKSPACE=/data/tmp/br-large-read-profile
export BR_CAPACITY_BINARY=/data/tmp/br-release/release/br
export BR_NUMA_PROFILE_DIR=tests/artifacts/perf/beads-perf-<timestamp>-numa-read-command-profile

mkdir -p "$BR_CAPACITY_REPORT_DIR"/{inputs,golden}
cp "$BR_NUMA_PROFILE_DIR/env.json" "$BR_CAPACITY_REPORT_DIR/inputs/numa-env.json"
cp "$BR_NUMA_PROFILE_DIR/timing/default-summary.json" \
  "$BR_CAPACITY_REPORT_DIR/inputs/read-default-summary.json"
cp "$BR_NUMA_PROFILE_DIR/timing/pinned-cpu0-summary.json" \
  "$BR_CAPACITY_REPORT_DIR/inputs/read-pinned-cpu0-summary.json"

"$BR_CAPACITY_BINARY" --no-auto-import --no-auto-flush count --json \
  > "$BR_CAPACITY_REPORT_DIR/inputs/count.json"
"$BR_CAPACITY_BINARY" --no-auto-import --no-auto-flush sync --status --json \
  > "$BR_CAPACITY_REPORT_DIR/inputs/sync-status.json"
"$BR_CAPACITY_BINARY" --no-auto-import --no-auto-flush doctor --json \
  > "$BR_CAPACITY_REPORT_DIR/inputs/doctor.json"
```

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

### Changelog Markdown Example Output

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/PLAN_TO_PORT_BEADS_WITH_SQLITE_AND_ISSUES_JSONL_TO_RUST.md

Example of a changelog generated in markdown format, detailing changes grouped by type.

```markdown
## Changelog (v1.0.0 → HEAD)

### Features
- Add dark mode support (bd-45)
- Implement user preferences (bd-52)

### Bug Fixes
- Fix login crash on empty password (bd-67)
- Resolve race condition in sync (bd-71)

### Chores
- Update dependencies (bd-80)
```

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

### JSON Error Hint Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TROUBLESHOOTING.md

An example of a JSON error response that provides hints and context for an 'ISSUE_NOT_FOUND' error.

```json
{
  "error": {
    "code": "ISSUE_NOT_FOUND",
    "hint": "Did you mean 'bd-abc123'?",
    "context": {
      "searched_id": "bd-abc12",
      "similar_ids": ["bd-abc123", "bd-abc124"]
    }
  }
}
```

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

### Initialize a new project with br

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Initializes 'br' in the current project directory, creating a SQLite database and metadata file for issue tracking.

```bash
cd your-project
br init
```

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

### Install beads_rust on Fedora/RHEL

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs build dependencies, Rust nightly toolchain, and beads_rust using Cargo on Fedora/RHEL systems.

```bash
# Install build dependencies
sudo dnf install -y gcc pkg-config openssl-devel

# Install Rust and br
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup install nightly
rustup default nightly
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Beads CLI 'init' Command Behavior

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Details the behavior of the 'bd init' command, including directory creation, database setup, migration execution, and configuration.

```text
1. Creates `.beads/` directory
2. Creates `.beads/beads.db` SQLite database
3. Runs all migrations
4. Sets `issue_prefix` config if --prefix specified
5. Creates `.beads/.gitignore` with:
   ```
   beads.db
   beads.db-wal
   beads.db-shm
   bd.sock
   daemon.log
   export_hashes.db
   sync_base.jsonl
   ```
```

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

### Install beads_rust on Ubuntu/Debian

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs build dependencies, Rust nightly toolchain, and beads_rust using Cargo on Ubuntu/Debian systems.

```bash
# Install build dependencies
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev

# Install Rust nightly
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup install nightly
rustup default nightly

# Install br
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Build and Run MCP Serve

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/AGENTS.md

Build the binary with the `mcp` feature and run the MCP serve command. Configure the MCP client to launch `br serve` via stdio.

```bash
MCP_TARGET="${TMPDIR:-/tmp}/rch_target_beads_rust_${AGENT_NAME:-agent}"
rch exec -- env CARGO_TARGET_DIR="$MCP_TARGET" cargo build --release --features mcp
RUST_LOG=error "$MCP_TARGET/release/br" serve --actor "${AGENT_NAME:-mcp}"
```

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

### Example Valid events.jsonl

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/ARTIFACT_LOG_SCHEMA.md

An example of a correctly formatted events.jsonl file, which logs command and snapshot events during test execution.

```jsonl
{"timestamp":"2026-01-17T12:34:56.000Z","event_type":"command","label":"init","binary":"br","args":["init"],"cwd":"/tmp/test","exit_code":0,"success":true,"duration_ms":42,"stdout_len":64,"stderr_len":0,"stdout_path":"0001_init.stdout","stderr_path":null,"snapshot_path":null}
{"timestamp":"2026-01-17T12:34:56.100Z","event_type":"snapshot","label":"after_init","binary":"","args":[],"cwd":"/tmp/test","exit_code":0,"success":true,"duration_ms":0,"stdout_len":0,"stderr_len":0,"stdout_path":null,"stderr_path":null,"snapshot_path":"after_init.snapshot.json"}
{"timestamp":"2026-01-17T12:34:56.200Z","event_type":"command","label":"create","binary":"br","args":["create","--title","Test issue"],"cwd":"/tmp/test","exit_code":0,"success":true,"duration_ms":15,"stdout_len":32,"stderr_len":0,"stdout_path":"0002_create.stdout","stderr_path":null,"snapshot_path":null}
```

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

### List Actionable Work

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

The `ready` command shows issues that are currently actionable.

```bash
br ready
```

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

### Get Specific Configuration Value

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TROUBLESHOOTING.md

Retrieve the value of a specific configuration key using 'br config get <key>'.

```bash
br config get <key>
```

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

### Build beads_rust from Source

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Clones the repository, builds the release binary, and optionally installs it locally or system-wide. Use `--release` for optimized builds.

```bash
# Clone the repository
git clone https://github.com/Dicklesworthstone/beads_rust.git
cd beads_rust

# Build release binary (optimized for size)
cargo build --release

# The binary is at ./target/release/br
./target/release/br --version

# Optional: Install system-wide
sudo cp target/release/br /usr/local/bin/
# Or for user-local install
cp target/release/br ~/.local/bin/
```

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

### Session Start: Capture Initial State

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/AGENT_INTEGRATION.md

Begin a session by capturing the initial state of ready issues in JSON format to a temporary file.

```bash
# Session start
br ready --json > /tmp/session_start.json

```

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

### Install Rust nightly toolchain

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs and sets the Rust nightly toolchain, which is required for certain unstable features like edition 2024.

```bash
rustup install nightly
rustup default nightly
# Or use: rustup run nightly cargo install ...
```

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

### BR Agent Workflow Example (After Migration)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/skills/bd-to-br-migration/SKILL.md

This markdown snippet illustrates the agent workflow using the 'br' command after migration, including the necessary manual git steps.

```markdown
## Issue Tracking with br (beads_rust)

**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.

Key invariants:
- `.beads/` is authoritative

### Agent workflow:
1. `br ready` to find work
2. `br update <id> --status in_progress`
3. Implement
4. `br close <id>`
5. Sync and commit:
   ```bash
   br sync --flush-only
   git add .beads/
   git commit -m "sync beads"
   ```
```

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

### Setup NUMA/High-Core Read-Command Profile

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TEST_HARNESS.md

Set up environment variables and directories for NUMA/high-core read-command profiling. This involves defining output directories, workspace, and binary paths, and creating necessary subdirectories.

```bash
export BR_NUMA_PROFILE_DIR=tests/artifacts/perf/beads-perf-<timestamp>-numa-read-command-profile
export BR_NUMA_PROFILE_WORKSPACE=/data/tmp/br-large-read-profile
export BR_NUMA_PROFILE_BINARY=/data/tmp/br-release/release/br

mkdir -p "$BR_NUMA_PROFILE_DIR"/{env,commands,golden,timing,syscalls,raw}
lscpu > "$BR_NUMA_PROFILE_DIR/env/lscpu.txt"
lscpu --json > "$BR_NUMA_PROFILE_DIR/env/lscpu.json"
numactl --hardware > "$BR_NUMA_PROFILE_DIR/env/numactl-hardware.txt"
free -b > "$BR_NUMA_PROFILE_DIR/env/free-bytes.txt"
```

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

### Build and run MCP server (local)

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/AGENT_INTEGRATION.md

Commands to build the `br` binary with the `mcp` feature enabled and then run the MCP server locally, logging errors.

```bash
cargo build --release --features mcp
RUST_LOG=error ./target/release/br serve --actor codex
```

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

### Install beads_rust on Arch Linux

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/INSTALLING.md

Installs the Rust package and beads_rust using Cargo on Arch Linux systems. Requires Rust nightly toolchain.

```bash
# Install dependencies
sudo pacman -S rust

# Install br
rustup install nightly
rustup default nightly
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git
```

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

### Manual Build and Client Launch for MCP Serve

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/SWARM_SCALE_TUNING.md

Build the release version of `br` with the `mcp` feature enabled and launch the MCP serve client. This is used for setting up the MCP serve topology.

```bash
MCP_TARGET="/data/tmp/br-mcp-target-${AGENT_NAME:-mcp}"
cargo build --release --features mcp --target-dir "$MCP_TARGET"
RUST_LOG=error "$MCP_TARGET/release/br" serve --actor "${AGENT_NAME:-mcp}"
```

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

### Initialize and Use br - Beads Rust

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

Quick example demonstrating how to initialize br in a project and add agent instructions to AGENTS.md. The 'br init' command sets up the repository, and 'br agents --add --force' manages agent instructions.

```bash
# Initialize br in your project
cd my-project
br init

# Add agent instructions to AGENTS.md (creates file if needed)
br agents --add --force
```

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

### Verify ACFS Installer Notification Workflow

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/CI_SUPPLY_CHAIN.md

Execute the local harness for the ACFS installer notification workflow to test checksums, branch logic, and payload.

```bash
./scripts/verify-notify-acfs-workflow.sh
```

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

### SQLite Connection String Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Example of a SQLite connection string for Beads, including pragmas for foreign keys, busy timeout, and journal mode.

```sql
file:path/to/beads.db?_pragma=foreign_keys(ON)&_pragma=busy_timeout(30000)&_pragma=journal_mode(WAL)
```

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

### Dependency Tree Output - Mermaid Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Example of the Mermaid syntax output for the 'bd dep tree' command, suitable for rendering dependency graphs.

```mermaid
graph TD
    bd-epic-1["Epic: User Management"]
    bd-task-1["P1: Design schema"]
    bd-epic-1 --> bd-task-1
    ...

```

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

### Initialize New Beads Workspace

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/TROUBLESHOOTING.md

Run 'br init' to create a new Beads workspace. Use '--prefix' to specify a custom project name.

```bash
br init
```

```bash
br init --prefix myproj
```

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

### Create OutputContext from Args

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/plans/RICH_INTEGRATION_PLAN.md

Initializes the OutputContext based on global CLI arguments. Detects the appropriate output mode and configures the console accordingly.

```rust
use rich_rust::prelude::*;
use crate::cli::GlobalArgs;

/// Central output coordinator that respects robot/json/quiet modes.
pub struct OutputContext {
    /// Rich console for human-readable output
    console: Console,
    /// Theme for consistent styling
    theme: Theme,
    /// Output mode
    mode: OutputMode,
    /// Terminal width (cached)
    width: usize,
}

impl OutputContext {
    /// Create from CLI global args
    pub fn from_args(args: &GlobalArgs) -> Self {
        let mode = Self::detect_mode(args);
        let console = Self::create_console(mode);
        let width = console.width();

        Self {
            console,
            theme: Theme::default(),
            mode,
            width,
        }
    }

    fn detect_mode(args: &GlobalArgs) -> OutputMode {
        // Priority order (highest first):
        // 1. --json flag → Json mode
        // 2. --quiet flag → Quiet mode
        // 3. --no-color flag → Plain mode
        // 4. Not a TTY (piped) → Plain mode
        // 5. Otherwise → Rich mode

        if args.json {
            return OutputMode::Json;
        }
        if args.quiet {
            return OutputMode::Quiet;
        }
        if args.no_color || std::env::var("NO_COLOR").is_ok() {
            return OutputMode::Plain;
        }
        if !is_terminal() {
            return OutputMode::Plain;
        }
        OutputMode::Rich
    }

    fn create_console(mode: OutputMode) -> Console {
        match mode {
            OutputMode::Rich => Console::new(),
            OutputMode::Plain | OutputMode::Quiet => {
                Console::builder()
                    .color_system(None)
                    .force_terminal(false)
                    .build()
            }
            OutputMode::Json => {
                // JSON mode doesn't use console, but create minimal one
                Console::builder()
                    .color_system(None)
                    .force_terminal(false)
                    .build()
            }
        }
    }

    // ─────────────────────────────────────────────────────────────
    // Mode Checks
    // ─────────────────────────────────────────────────────────────

    pub fn is_rich(&self) -> bool { self.mode == OutputMode::Rich }
    pub fn is_json(&self) -> bool { self.mode == OutputMode::Json }
    pub fn is_quiet(&self) -> bool { self.mode == OutputMode::Quiet }
    pub fn is_plain(&self) -> bool { self.mode == OutputMode::Plain }
    pub fn width(&self) -> usize { self.width }

    // ─────────────────────────────────────────────────────────────
    // Output Methods (route based on mode)
    // ─────────────────────────────────────────────────────────────

    /// Print styled text (respects mode)
    pub fn print(&self, content: &str) {
        match self.mode {
            OutputMode::Rich => self.console.print(content),
            OutputMode::Plain => {
                // Strip markup, print plain
                println!("{}", strip_markup(content));
            }
            OutputMode::Quiet => { /* suppress */ } 
            OutputMode::Json => { /* JSON output handled separately */ } 
        }
    }

    /// Print a renderable component
    pub fn render<R: Renderable>(&self, renderable: &R) {
        if self.is_rich() {
            self.console.print_renderable(renderable);
        }
    }

    /// Print JSON (only in JSON mode)
    pub fn json<T: serde::Serialize>(&self, value: &T) {
        if self.is_json() {
            println!("{}", serde_json::to_string(value).unwrap());
        }
    }

    /// Print JSON pretty (human mode with --json-pretty or similar)
    pub fn json_pretty<T: serde::Serialize>(&self, value: &T) {
        if self.is_rich() {
            let json = rich_rust::renderables::Json::from_value(
                serde_json::to_value(value).unwrap()
            );
            self.console.print_renderable(&json);
        } else if self.is_json() {
            println!("{}", serde_json::to_string_pretty(value).unwrap());
        }
    }

    // ─────────────────────────────────────────────────────────────
    // Semantic Output Methods
    // ─────────────────────────────────────────────────────────────

    /// Success message (green checkmark)
    pub fn success(&self, message: &str) {
        match self.mode {
            OutputMode::Rich => {
                self.console.print(&format!(

```

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

### Open Configuration Editor

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/README.md

Open the 'br' configuration file in the default editor. Use this for manual configuration changes.

```bash
br config edit
```

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

### Blocked Issues Output - JSON Example

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/docs/porting/EXISTING_BEADS_STRUCTURE_AND_ARCHITECTURE.md

Example JSON output for the 'bd blocked' command, detailing blocked issues and the IDs and statuses of the issues they are blocked by.

```json
{
  "blocked_issues": [
    {
      "issue": {...},
      "blocked_by": [
        {"id": "bd-xyz789", "status": "open", "title": "..."}
      ]
    }
  ],
  "count": 2
}
```

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

### Run Baseline Ready Command

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/tests/artifacts/perf/beads-perf-20260503T174524Z-scheduler-slice/MANIFEST.md

Executes the 'ready' command without auto-import or auto-flush, limiting output to 0 and formatting as JSON. Use this to establish a baseline for ready parity.

```bash
/tmp/br-before-scheduler-slice --no-auto-import --no-auto-flush ready --limit 0 --json
```

```bash
/tmp/rch_target_beads_rust_dustypuma_blocked_projection_local/release/br --no-auto-import --no-auto-flush ready --limit 0 --json
```

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

### Cass Tool Examples

Source: https://github.com/dicklesworthstone/beads_rust/blob/main/AGENTS.md

Examples of using the 'cass' tool for searching and managing agent conversations. Always use --robot or --json flags.

```bash
cass health
```

```bash
cass search "async runtime" --robot --limit 5
```

```bash
cass view /path/to/session.jsonl -n 42 --json
```

```bash
cass expand /path/to/session.jsonl -n 42 -C 3 --json
```

```bash
cass capabilities --json
```

```bash
cass robot-docs guide
```