br - Beads Rust

A Rust port of Steve Yegge's beads, frozen at the "classic" SQLite + JSONL architecture I built my Agent Flywheel tooling around.

Quick Start | Commands | Configuration | VCS Integration | FAQ

Quick Install

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

Works on Linux, macOS, and Windows (WSL). Auto-detects your platform and downloads the right binary.

Useful install flags: --skip-skills to skip all Claude Code / Codex skills, or --no-migration-skill to skip just the bd-to-br-migration skill (handy for clean agent sandboxes where you're only using br).

Why This Project Exists

I (Jeffrey Emanuel) LOVE Steve Yegge's Beads project. Discovering it and seeing how well it worked together with my MCP Agent Mail was a truly transformative moment in my development workflows and professional life. This quickly also led to beads_viewer (bv), which added another layer of analysis to beads that gives swarms of agents the insight into what beads they should work on next to de-bottleneck the development process and increase velocity. I'm very grateful for finding beads when I did and to Steve for making it.

At this point, my Agent Flywheel System is built around beads operating in a specific way. As Steve continues evolving beads toward GasTown and beyond, our use cases have naturally diverged. The hybrid SQLite + JSONL-git architecture that I built my tooling around (and independently mirrored in MCP Agent Mail) is being replaced with approaches better suited to Steve's vision.

Rather than ask Steve to maintain a legacy mode for my niche use case, I created this Rust port that freezes the "classic beads" architecture I depend on. The command is br to distinguish it from the original bd.

This isn't a criticism of beads; Steve's taking it in exciting directions. It's simply that my tooling needs a stable snapshot of the architecture I built around, and maintaining my own fork is the right solution for that. Steve has given his full endorsement of this project.

TL;DR

The Problem

You need to track issues for your project, but: - GitHub/GitLab Issues require internet, fragment context from code, and don't work offline - TODO comments get lost, have no status tracking, and can't express dependencies - External tools (Jira, Linear) add overhead, require context switching, and cost money

The Solution

br is a local-first issue tracker that stores issues in SQLite with JSONL export for git-friendly collaboration. It provides dependency-aware issue tracking, machine-readable output, sync/recovery tooling, and agent-friendly workflows without leaving your repository.

br init                              # Initialize in your repo
br create "Fix login timeout" -p 1   # Create high-priority issue
br ready                             # See what's actionable
br coordination status --json        # Inspect hidden in-progress claims
br close br-abc123                   # Close when done; JSONL auto-flushes by default
br sync --flush-only                 # Optional final export check before git commit

Why br?

Quick Example

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

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

# Create issues with priority (0=critical, 4=backlog)
br create "Implement user auth" --type feature --priority 1
# Created: br-7f3a2c

br create "Set up database schema" --type task --priority 1
# Created: br-e9b1d4

# Auth depends on database schema
br dep add br-7f3a2c br-e9b1d4

# See what's ready to work on (not blocked)
br ready
# br-e9b1d4  P1  task     Set up database schema

# Claim and complete work
br update br-e9b1d4 --status in_progress
br close br-e9b1d4 --reason "Schema implemented"

# Now auth is unblocked
br ready
# br-7f3a2c  P1  feature  Implement user auth

# Mutations auto-flushed JSONL by default; run an idempotent final export check
br sync --flush-only
git add .beads/ && git commit -m "Update issues"

Design Philosophy

1. Non-Invasive by Default

For normal issue tracking and sync, br keeps its state in .beads/ and leaves git handoff to you. It never commits, pushes, pulls, installs hooks, or runs as a background service.

Some explicit commands intentionally step outside that default storage boundary: br agents edits requested agent-instruction files, br doctor --repair can fix the project .gitignore, br config edit/set updates config files, br completions -o writes shell completion files, br upgrade updates the installed binary, and git-reporting commands such as br changelog, br orphans, and commit-activity br stats inspect git history.

# Normal issue state lives under .beads/
ls -la .beads/
# beads.db       # SQLite database
# issues.jsonl   # Git-friendly export
# config.yaml    # Optional config

2. SQLite + JSONL Hybrid

SQLite for fast local queries. JSONL for git-friendly collaboration.

# Local: Fast queries via SQLite
br list --priority 0-1 --status open --assignee alice

# Collaboration: JSONL merges cleanly in git
git diff .beads/issues.jsonl
# +{"id":"br-abc123","title":"New feature",...}

3. Explicit Over Implicit

State changes are explicit. Successful mutating commands update SQLite and auto-flush JSONL by default, but br still never commits, pushes, pulls, or imports remote changes without a command. Git-inspection behavior is limited to explicit reporting commands and reads history only.

# Mutations auto-flush .beads/issues.jsonl by default
br close br-abc123 --reason "Done"

# Re-run export after --no-auto-flush/config changes, recovery, or as a final check
br sync --flush-only

# Import is explicit (not automatic)
br sync --import-only

# Merge divergent DB and JSONL edits using the saved base snapshot
br sync --merge

# Rebuild SQLite from authoritative JSONL after recovery/corruption
br sync --import-only --rebuild

# Git operations are YOUR responsibility
git add .beads/ && git commit -m "..."

4. Agent-First Design

Every command supports --json for AI coding agents:

br list --json | jq '.issues[] | select(.priority <= 1)'
br ready --json  # Structured output for agents
br show br-abc123 --json
br capabilities --format json
br capabilities --format json --command "create"
br robot-docs guide

For routine operator or agent use, prefer RUST_LOG=error br ... to suppress internal Rust dependency logs while preserving normal stdout/JSON output:

RUST_LOG=error br ready --json
RUST_LOG=error br sync --flush-only

5. Rich Terminal Output

Interactive terminals get enhanced visual output:

# Rich mode (default in TTY)
br list           # Formatted tables with colors
br show br-abc    # Styled panels with metadata

# Plain mode (piped or --no-color)
br list | cat     # Clean text, no ANSI codes

# JSON mode (--json or --robot)
br list --json    # Structured output for tools ({issues, total, limit, offset, has_more})

Output mode is auto-detected: - Rich: Interactive TTY with color support - Plain: Piped output or NO_COLOR environment - JSON: Machine-readable (--json flag) - Quiet: Minimal output (--quiet flag)

6. Focused Local Scope

br has grown into a full CLI surface for local issue tracking: routing, recovery, TOON/JSON schemas, MCP support, conformance checks, and sync safety tools are all part of the current scope. The focus is still local-first operation, explicit git/VCS handoff, and no background services installed behind your back.

Comparison vs Alternatives

br vs Original beads (Go)

When to use br: You want a stable, local-first issue tracker with explicit sync, dependency-aware planning, and machine-readable output.

When to use beads: You want advanced features like Linear/Jira sync, RPC daemon, automatic hooks.

br vs GitHub Issues

br vs Linear/Jira

Installation

Quick Install (Recommended)

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

From Source

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

# Or install globally
cargo install --path .

Cargo Install

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

Note: cargo install places binaries in ~/.cargo/bin/, while the install script uses ~/.local/bin/. If you have both in PATH, ensure the desired location has higher priority to avoid running an outdated version. Run which br to verify which binary is active.

Disable Self-Update

# Build without self-update feature
cargo build --release --no-default-features

# Or install without it
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git --no-default-features

Enable MCP Server Support

br serve is optional and is not built by the default feature set. Build with the mcp feature when you want an AI agent to talk to br over the Model Context Protocol instead of shelling out to CLI commands.

cargo build --release --features mcp

# Or install globally with MCP support
cargo install --git https://github.com/Dicklesworthstone/beads_rust.git --features mcp

Run it from an initialized beads workspace:

RUST_LOG=error br serve --actor codex

The server uses MCP over stdio. It is launched by an MCP client, does not listen on a network port, and uses the same SQLite database, JSONL export path, write locks, audit events, and sync safety model as the normal CLI. It does not run git. Use shell/JSON commands for simple scripts; use MCP when an agent benefits from discoverable tools, resources, prompts, and structured recovery hints. MCP clients can read beads://coordination/status for the same br.coordination.v1 stale-claim evidence shape as br coordination status --json; use the CLI snapshot flags when Agent Mail reservation or liveness evidence is required.

Verify Installation

br --version
# br 0.1.45

Quick Start

1. Initialize in Your Project

cd my-project
br init
# Initialized beads workspace in .beads/

2. Create Your First Issue

br create "Fix login timeout bug" \
  --type bug \
  --priority 1 \
  --description "Users report login times out after 30 seconds"
# Created: br-a1b2c3

3. Add Labels

br label add br-a1b2c3 backend auth

4. Check Ready Work

br ready
# Shows issues that are open, not blocked, not deferred

5. Claim and Work

br update br-a1b2c3 --status in_progress --assignee "$(git config user.email)"

6. Close When Done

br close br-a1b2c3 --reason "Increased timeout to 60s, added retry logic"

7. Sync to Git

br sync --flush-only        # Idempotent final JSONL export check
git add .beads/             # Stage changes
git commit -m "Fix: login timeout (br-a1b2c3)"

Commands

Issue Lifecycle