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

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

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

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.

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

Querying

Dependencies

Labels

Comments

Planning & Reporting

Agents & Tooling

Sync & System

Global Flags

Configuration

br uses layered configuration:

1. CLI flags (highest priority)
2. Environment variables
3. Project config: .beads/config.yaml
4. User config: ~/.config/beads/config.yaml
5. Defaults (lowest priority)

Example Config

# .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

Config Commands

# Show all config
br config list

# Get specific value
br config get id.prefix

# Set value
br config set defaults.priority=1

# Open in editor
br config edit

Environment Variables

Recommended default for normal CLI use:

export RUST_LOG=error

This keeps successful commands readable by suppressing low-level dependency logging. Remove or override it when debugging br internals.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                         CLI (br)                              │
│  Commands: create, list, ready, close, sync, etc.            │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│                      Storage Layer                            │
│  ┌─────────────────┐              ┌─────────────────────┐    │
│  │  SqliteStorage  │◄────────────►│  JSONL Export/Import │    │
│  │                 │   sync       │                     │    │
│  │  - WAL mode     │              │  - Atomic writes    │    │
│  │  - Dirty track  │              │  - Content hashing  │    │
│  │  - Blocked cache│              │  - Merge support    │    │
│  └────────┬────────┘              └──────────┬──────────┘    │
└───────────│──────────────────────────────────│───────────────┘
            │                                  │
            ▼                                  ▼
     .beads/beads.db                    .beads/issues.jsonl
     (Primary storage)                  (Git-friendly export)

Data Flow

User Action                    br Command              Storage
───────────────────────────────────────────────────────────────
Create issue        ──►      br create        ──►    SQLite INSERT
                                              ──►    Mark dirty

Update issue        ──►      br update        ──►    SQLite UPDATE
                                              ──►    Mark dirty

Query issues        ──►      br list          ──►    SQLite SELECT

Export to git       ──►      br sync          ──►    Write JSONL
                             --flush-only     ──►    Clear dirty flags

Pull from git       ──►      git pull         ──►    JSONL updated
                    ──►      br sync          ──►    Merge to SQLite
                             --import-only

Safety Model

br sync is designed to be provably safe:

Troubleshooting

Error: "Database locked"

Cause: Another process has the database open.

# Check for other br processes
pgrep -f "br "

# Force close and retry
br sync --status  # Safe read-only check

Error: "Issue not found"

Cause: Issue ID doesn't exist or was deleted.

# Check if issue exists
br list --json | jq '.issues[] | select(.id == "br-abc123")'

# Check for similar IDs
br list | grep -i "abc"

Error: "Prefix mismatch"

Cause: This now only applies when you explicitly ask br to enforce or rewrite prefixes during import. Mixed prefixes in a project are supported by default.

# Check your default creation prefix
br config get id.prefix

# Import while rewriting IDs into your configured default prefix
br sync --import-only --rename-prefix

If you want to preserve imported IDs exactly as-is, omit --rename-prefix.

Error: "Stale database"

Cause: JSONL has issues that don't exist in database.

# Check sync status
br sync --status

# Force import (may lose local changes)
br sync --import-only --force

# If JSONL is authoritative, rebuild SQLite to match it exactly
br sync --import-only --rebuild

--rebuild is an import-mode operation. It is not valid with --flush-only or --merge; after import it removes database entries that are absent from JSONL, while preserving deletion tombstones used by sync.

Sync Issues After Git Merge

# 1. Check for JSONL merge conflicts
git status .beads/

# 2. If conflicts, resolve manually then:
br sync --import-only

# 3. If both SQLite and JSONL changed cleanly, run a three-way merge:
br sync --merge

# 4. If database seems stale:
br doctor

br sync --merge uses .beads/beads.base.jsonl as the common ancestor. If the same issue changed on both sides, br stops and asks for an explicit policy: --force-db keeps the local SQLite version, --force-jsonl keeps the JSONL version, and --force keeps the newer timestamp.

Command Output is Garbled

# Disable colors
br list --no-color

# Or use JSON output
br list --json | jq '.issues'

Limitations

br intentionally does not support:

FAQ

Q: How do I integrate with beads_viewer (bv)?

br works seamlessly with beads_viewer:

# Use bv for interactive TUI
bv

# Use br for CLI/scripting
br ready --json | jq

Q: Can I use br with AI coding agents?

Yes! br is designed for AI agent integration:

# Agents can use --json for structured output
br list --json
br ready --json
br show br-abc123 --json

# Create issues programmatically
br create "Title" --json  # Returns created issue as JSON

See AGENTS.md for the complete agent integration guide.

Q: How do I migrate from the original beads?

br uses the same JSONL format as classic beads:

# Copy your existing issues.jsonl
cp /path/to/beads/.beads/issues.jsonl .beads/

# Import into br
br sync --import-only

Q: Why Rust instead of Go?

• Smaller binary: ~5-8 MB vs ~30+ MB
• Memory safety: No runtime garbage collection
• Operational fit: The CLI, release pipeline, and agent tooling are already Rust-based
• Personal preference: The author's flywheel tooling is Rust-based

Q: How do dependencies work?

# Issue A depends on Issue B (A is blocked until B is closed)
br dep add br-A br-B

# Now br-A won't appear in `br ready` until br-B is closed
br ready  # Only shows br-B

# Close the blocker
br close br-B

# Now br-A is ready
br ready  # Shows br-A

Q: How do I handle merge conflicts in JSONL?

JSONL is line-based, so conflicts are usually easy to resolve:

# After git merge with conflicts
git status .beads/issues.jsonl

# Edit to resolve (each line is one issue)
vim .beads/issues.jsonl

# Mark resolved and import
git add .beads/issues.jsonl
br sync --import-only

If git merged .beads/issues.jsonl without textual conflict markers but both SQLite and JSONL have independent br changes, use the sync merge path instead:

br sync --merge

# If br reports semantic conflicts, choose one resolution policy:
br sync --merge --force-db     # keep local SQLite changes
br sync --merge --force-jsonl  # keep JSONL changes
br sync --merge --force        # keep the newer timestamp

Q: Can I customize the issue ID prefix?

Yes:

br config set id.prefix=myproj
# New issues: myproj-abc123

You can also mix multiple prefixes in the same project. The configured prefix is the default for newly created issues, not a restriction on existing IDs.

Q: Where is data stored?

.beads/
├── beads.db        # SQLite database (primary storage)
├── issues.jsonl    # JSONL export (for git)
├── config.yaml     # Project configuration
├── routes.jsonl    # Optional cross-project prefix routes
└── metadata.json   # Workspace metadata

Q: Can one workspace refer to issues in another workspace?

Yes, with explicit cross-project routing. Add one JSON object per line to .beads/routes.jsonl:

{"prefix":"api-","path":"../api"}
{"prefix":"ops-","path":"/srv/projects/ops/.beads"}

When an issue ID starts with a routed prefix, route-aware commands resolve that ID against the target workspace's .beads directory. The path can point at a project root or directly at a .beads/_beads directory; relative paths are resolved from the workspace root, and town-level routing can also be discovered from a parent with mayor/town.json.

Common route-aware operations include show, update, close, reopen, delete, defer, comments, label, dep, graph, audit, and lint. Routed mutations acquire the target workspace write lock and update the target workspace's storage, not the caller's local database.

This is not automatic multi-repo synchronization. Routed issue operations still do not push or pull remote repositories, copy issues between repositories, or provide real-time collaboration. Routes are a local dispatch table for explicit cross-workspace operations. Commit and synchronize each affected repository's .beads/ files through your normal VCS workflow.

External dependency status checks use explicit dependency IDs such as external:api:api-123 together with configured external_projects.<name> paths. They let ready, blocked, show, dep, and stats account for blockers in other workspaces without importing those issues into the local database.

AI Agent Integration

br is designed for AI coding agents. See AGENTS.md for:

• JSON output schemas
• Workflow patterns
• Integration with MCP Agent Mail
• Degraded coordination when Agent Mail is unavailable
• Robot mode flags
• Best practices

You can also emit machine-readable JSON Schema documents directly:

br schema all --format json | jq '.schemas.Issue'
br schema issue-details --format toon

VCS Integration

Using non-git version control? See VCS_INTEGRATION.md for equivalent commands and workflows.

Quick example:

# Agent workflow
br ready --json | jq '.[0]'           # Get top priority
br update br-abc --status in_progress # Claim work
# ... do work ...
br close br-abc --reason "Completed"  # Done; JSONL auto-flushes by default
br sync --flush-only                  # Final export check before staging .beads/

Community Projects

• Beads Task-Issue Tracker — A desktop GUI for br, built with Tauri + Nuxt. Reads the same SQLite + JSONL files that br produces, providing a graphical interface for browsing and managing issues.

About Contributions

Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

MIT License (with OpenAI/Anthropic Rider) — see LICENSE for details.