GitHub - Dicklesworthstone/beads_rust: A fast Rust port of Steve Yegge's beads - a local-first, non-invasive issue tracker for git repositories

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.

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 bd-abc123                   # Close when done
br sync --flush-only                 # Export for git commit

# 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: bd-7f3a2c

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

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

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

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

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

# Export to JSONL for git commit
br sync --flush-only
git add .beads/ && git commit -m "Update issues"

# br only touches .beads/ directory
ls -la .beads/
# beads.db       # SQLite database
# issues.jsonl   # Git-friendly export
# config.yaml    # Optional config

# 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":"bd-abc123","title":"New feature",...}

# Export is explicit (not automatic)
br sync --flush-only

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

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

br list --json | jq '.[] | select(.priority <= 1)'
br ready --json  # Structured output for agents
br show bd-abc123 --json

# Rich mode (default in TTY)
br list           # Formatted tables with colors
br show bd-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

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

# 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 --git https://github.com/Dicklesworthstone/beads_rust.git

# 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

br --version
# br 0.1.0 (rustc 1.85.0-nightly)

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

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

br label add bd-a1b2c3 backend auth

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

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

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

br sync --flush-only        # Export DB to JSONL
git add .beads/             # Stage changes
git commit -m "Fix: login timeout (bd-a1b2c3)"

# .beads/config.yaml

# Issue ID prefix (default: "bd")
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

# 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

┌──────────────────────────────────────────────────────────────┐
│                         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)

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

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

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

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

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

# Check your prefix
br config --get id.prefix

# Import with validation skip (careful!)
br sync --import-only --skip-prefix-validation

# Check sync status
br sync --status

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

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

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

# 3. If database seems stale:
br doctor

# Disable colors
br list --no-color

# Or use JSON output
br list --json | jq

# Use bv for interactive TUI
bv

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

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

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

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

# Import into br
br sync --import-only

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

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

# Close the blocker
br close bd-B

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

# 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

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

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

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

# Agent workflow
bd ready --json | jq '.[0]'           # Get top priority
bd update bd-abc --status in_progress # Claim work
# ... do work ...
bd close bd-abc --reason "Completed"  # Done
bd sync --flush-only                  # Export for git