Br

<!-- TOC: Critical Rules | Quick Workflow | Essential Commands | Dependencies | Sync | bv Integration | Agent Mail | Troubleshooting | References -->

br -- Beads Rust Issue Tracker (Official Skill)

Non-invasive: br NEVER runs git commands. Sync and commit are YOUR responsibility.

Critical Rules for Agents

Quick Workflow

ACTOR="${BR_ACTOR:-assistant}"

# 1. Find work
br ready --json

# 2. Claim it
br update --actor "$ACTOR" <id> --status in_progress

# 3. Do work...

# 4. Complete
br close --actor "$ACTOR" <id> --reason "Implemented X"

# 5. Sync to git (EXPLICIT!)
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"

Essential Commands

Issue Lifecycle

ACTOR="${BR_ACTOR:-assistant}"

br init                                              # Initialize .beads/ workspace
br create --actor "$ACTOR" "Title" -p 1 -t task      # Create issue (priority 0-4)
br q --actor "$ACTOR" "Quick note"                   # Quick capture (ID only output)
br show <id> --json                                  # Show issue details
br update --actor "$ACTOR" <id> --status in_progress # Update status
br update --actor "$ACTOR" <id> --priority 0         # Change priority
br close --actor "$ACTOR" <id> --reason "Done"       # Close with reason
br close --actor "$ACTOR" <id1> <id2> --reason "..."  # Close multiple at once
br reopen --actor "$ACTOR" <id>                      # Reopen closed issue

Create Options

br create --actor "$ACTOR" "Title" \
  --priority 1 \             # 0-4 scale (0=critical, 4=backlog)
  --type task \              # task, bug, feature, epic, question, docs
  --assignee "user@..." \    # Optional assignee
  --labels backend,auth \    # Comma-separated labels
  --description "..."        # Detailed description

Update Options

br update --actor "$ACTOR" <id> \
  --title "New title" \
  --priority 0 \
  --status in_progress \     # open, in_progress, closed
  --assignee "new@..." \
  --add-label reliability \
  --parent <parent-id> \
  --claim                    # Shorthand for claim-and-start

Bulk update (batch triage):

br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json

Querying (always use --json for agents)

br ready --json                      # Actionable work (no blockers)
br list --json                       # All issues
br list --status open --sort priority --json  # Filter and sort
br list --priority 0-1 --json        # Filter by priority range
br list --assignee alice --json      # Filter by assignee
br blocked --json                    # Show blocked issues
br search "keyword" --json           # Full-text search
br show <id> --json                  # Issue details with dependencies
br stale --days 30 --json            # Stale issues
br count --by status --json          # Count with grouping

Dependencies

br dep add <child> <parent>          # child depends on parent
br dep add <id> <depends-on> --type blocks  # Explicit block type
br dep remove <child> <parent>       # Remove dependency
br dep list <id> --json              # List dependencies for issue
br dep tree <id> --json              # Show dependency tree
br dep cycles --json                 # Find circular deps (MUST be empty!)

Critical: br dep cycles must return empty. Circular dependencies break the dependency graph and make br ready unreliable.

Labels

br label add <id> backend auth       # Add multiple labels
br label remove <id> urgent          # Remove label
br label list <id>                   # List issue's labels
br label list-all                    # All labels in project

Comments

ACTOR="${BR_ACTOR:-assistant}"
br comments add --actor "$ACTOR" <id> --message "Triage note" --json
br comments list <id> --json

Sync (EXPLICIT -- never automatic)

br sync --flush-only                 # Export DB to JSONL (before git commit)
br sync --import-only                # Import JSONL to DB (after git pull)
br sync --status                     # Check sync status

Workflow after making changes:

br sync --flush-only
git add .beads/ && git commit -m "Update issues"

Workflow after pulling:

git pull
br sync --import-only

System and Diagnostics

br doctor                            # Full diagnostics
br stats --json                      # Project statistics
br config list                       # Show all configuration
br config get id.prefix              # Get specific value
br config set defaults.priority=1    # Set value
br where                             # Show workspace location
br version                           # Show version
br upgrade                           # Self-update (if enabled)
br lint --json                       # Lint issues for problems

Priority Scale

Issue Types

task, bug, feature, epic, question, docs

Output Formats

bv Integration

CRITICAL: Never run bare bv -- it launches interactive TUI and blocks.

# Always use --robot-* flags:
bv --robot-next                      # Single top pick + claim command
bv --robot-triage                    # Full triage with recommendations
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights | jq '.Cycles'   # Check graph health (must be empty)
bv --robot-priority                  # Priority misalignment detection
bv --robot-alerts                    # Stale issues, blocking cascades

Agent Mail Coordination

Use bead ID as thread_id for multi-agent coordination:

# 1. Reserve files for bead
file_reservation_paths(..., reason="bd-123")

# 2. Announce work in thread
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

# 3. Do work...

# 4. Close bead and release
br close bd-123 --reason "Completed"
release_file_reservations(...)

Session Ending Pattern

Before ending any work session:

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # MUST show "up to date with origin"

Standard Agent Workflow (Full)

ACTOR="${BR_ACTOR:-assistant}"

# 1. Verify workspace
br where
br ready --json
br blocked --json
br list --status open --sort priority --json

# 2. Pick highest-priority ready work
br show <id> --json

# 3. Claim it
br update --actor "$ACTOR" <id> --status in_progress --claim

# 4. Do work...

# 5. Close with evidence
br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123"

# 6. Check queue impact
br ready --json
br blocked --json

# 7. Sync to git
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"
git push

Triage Decision Matrix

Classify each issue into exactly one category:

During large triage efforts, checkpoint every few updates:

br ready --json
br blocked --json

Anti-Patterns

• Running br sync without --flush-only or --import-only
• Forgetting sync before git commit
• Creating circular dependencies
• Running bare bv (blocks session)
• Assuming auto-commit behavior (br NEVER auto-commits)
• Inventing evidence for closure -- if unsure, comment instead
• Modifying unrelated issues during triage
• Adding speculative dependencies

Storage Layout

.beads/
  beads.db        # SQLite database (primary storage)
  beads.db-shm    # SQLite shared memory (WAL mode)
  beads.db-wal    # SQLite write-ahead log
  issues.jsonl    # JSONL export (for git)
  config.yaml     # Project configuration
  metadata.json   # Workspace metadata

Troubleshooting

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config list               # Check settings
which br                     # Verify br is installed

"Database locked": Check for other br processes with pgrep -f "br ".

Worktree error ('main' is already checked out):

git branch beads-sync main
br config set sync.branch beads-sync

Verbose debugging:

br -v list                   # Verbose
br -vv list                  # Debug
RUST_LOG=debug br list       # Detailed trace logs

References

br Command Reference

Global Flags

Actor Resolution

Resolve actor at runtime for all mutating commands:

ACTOR="${BR_ACTOR:-assistant}"

Use "$ACTOR" via --actor "$ACTOR" in all create/update/close/reopen/comment operations.

---

Issue Lifecycle

ACTOR="${BR_ACTOR:-assistant}"

br init                                              # Initialize workspace
br create --actor "$ACTOR" "Title" -p 1 --type bug   # Create issue
br q --actor "$ACTOR" "Quick note"                   # Quick capture (ID only)
br show <id> --json                                  # Show issue details
br update --actor "$ACTOR" <id> --priority 0         # Update fields
br close --actor "$ACTOR" <id> --reason "Done"       # Close with reason
br close --actor "$ACTOR" <id> --reason "..." --suggest-next --json  # Close and suggest next
br close --actor "$ACTOR" <id> --reason "..." --force --json         # Force close
br reopen --actor "$ACTOR" <id> --reason "..."       # Reopen closed issue
br delete <id>                                       # Delete issue (tombstone)

Create Options

br create --actor "$ACTOR" "Title" \
  --priority 1 \             # 0=critical, 1=high, 2=medium, 3=low, 4=backlog
  --type task \              # task, bug, feature, epic, question, docs
  --assignee "user@..." \    # Optional assignee
  --labels backend,auth \    # Comma-separated labels
  --description "..."        # Detailed description

Update Options

br update --actor "$ACTOR" <id> \
  --title "New title" \
  --priority 0 \
  --status in_progress \     # open, in_progress, closed
  --assignee "new@..." \
  --add-label reliability \
  --parent <parent-id> \
  --claim                    # Shorthand for claim-and-start

Bulk Update

br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json

---

Querying

br list --json                               # All issues
br list --status open --json                 # Filter by status
br list --status open --sort priority --json # Filter and sort
br list --priority 0-1 --json               # Filter by priority range
br list --assignee alice --json              # Filter by assignee

br ready --json                              # Actionable work (not blocked)
br blocked --json                            # Blocked issues

br search "authentication" --json            # Full-text search
br show <id> --json                          # Single issue detail

br stale --days 30 --json                    # Stale issues
br count --by status --json                  # Count with grouping
br stats --json                              # Project statistics
br lint --json                               # Lint issues for problems

---

Dependencies

br dep add <child> <parent>                  # child depends on parent
br dep add <id> <depends-on> --type blocks   # Explicit block type
br dep remove <child> <parent>               # Remove dependency
br dep list <id> --json                      # Dependencies for issue
br dep tree <id> --json                      # Dependency tree
br dep cycles --json                         # Circular deps (MUST be empty!)

---

Labels

br label add <id> backend auth               # Add multiple labels
br label remove <id> urgent                  # Remove label
br label list <id>                           # Issue's labels
br label list-all                            # All labels in project

---

Comments

ACTOR="${BR_ACTOR:-assistant}"
br comments add --actor "$ACTOR" <id> --message "Triage note" --json
br comments list <id> --json

---

Sync

br sync --flush-only                         # Export DB to JSONL
br sync --import-only                        # Import JSONL to DB
br sync --status                             # Check sync status

---

System

br doctor                                    # Run diagnostics
br where                                     # Show workspace location
br config list                               # Show all config
br config get id.prefix                      # Get specific value
br config set defaults.priority=1            # Set value
br version                                   # Show version
br upgrade                                   # Self-update (if enabled)

---

JSON Output Examples

# Get first ready issue
br ready --json | jq '.[0]'

# Filter high priority
br list --json | jq '.issues[] | select(.priority <= 1)'

# Get specific issue field
br show <id> --json | jq '.[0].title'

# Count open issues by type
br list --status open --json | jq '.issues | group_by(.type) | map({type: .[0].type, count: length})'

br Configuration

Configuration Precedence (High to Low)

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 File

# .beads/config.yaml

# Issue ID prefix (default: "bd")
id:
  prefix: "myproject"

# Default values for new issues
defaults:
  priority: 2        # P2 = MEDIUM (0-4 scale)
  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
  branch: beads-sync  # Use dedicated sync branch

---

Environment Variables

---

Config Commands

br config list                       # Show all config
br config get id.prefix              # Get specific value
br config set defaults.priority=1    # Set value

---

Storage Paths

Default storage is in .beads/ relative to project root:

.beads/
  beads.db        # SQLite database (primary storage)
  beads.db-shm    # SQLite shared memory (WAL mode)
  beads.db-wal    # SQLite write-ahead log
  issues.jsonl    # JSONL export (for git)
  config.yaml     # Project configuration
  metadata.json   # Workspace metadata

br Integration Patterns

bv (Beads Viewer) Integration

bv is a graph-aware triage engine for beads projects.

CRITICAL: Never run bare bv -- it launches interactive TUI and blocks the session.

# Always use --robot-* flags:
bv --robot-triage        # Full triage with recommendations
bv --robot-next          # Single top pick + claim command
bv --robot-plan          # Parallel execution tracks
bv --robot-insights      # Graph metrics (PageRank, cycles, etc.)
bv --robot-priority      # Priority misalignment detection
bv --robot-alerts        # Stale issues, blocking cascades
bv --robot-suggest       # Hygiene: duplicates, missing deps

Check Graph Health

bv --robot-insights | jq '.Cycles'       # Must be empty
bv --robot-insights | jq '.bottlenecks'  # Find blocking issues

Scoping and Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank

---

MCP Agent Mail Integration

Use bead IDs as coordination threads for multi-agent work:

Mapping Cheat Sheet

Agent Mail Workflow

# 1. Reserve files for bead
file_reservation_paths(..., reason="bd-123")

# 2. Announce work in thread
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

# 3. Do work...

# 4. Close bead when done
br close bd-123 --reason "Completed"

# 5. Release reservations
release_file_reservations(...)

---

Multi-Agent Coordination

When multiple agents work on the same project:

1. Use Agent Mail file reservations to avoid conflicts 2. Use bead ID as thread_id for communication 3. Check `br ready --json` to see unblocked work 4. Close beads when done to unblock dependents

Finding Parallel Work

# Get parallel execution tracks
bv --robot-plan

# Multiple agents can work on independent branches of the dependency graph

---

Standard Agent Workflow

ACTOR="${BR_ACTOR:-assistant}"

# 1. Find work
br ready --json

# 2. Claim work
br update --actor "$ACTOR" <id> --status in_progress --claim

# 3. Reserve edit surface (via Agent Mail)
# file_reservation_paths(..., reason="<id>")

# 4. Do work...

# 5. Complete
br close --actor "$ACTOR" <id> --reason "Implemented feature X"

# 6. Sync to git
br sync --flush-only
git add .beads/
git commit -m "feat: implement X (<id>)"

---

Session Ending Pattern

Before ending any session:

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # MUST show "up to date with origin"

---

Creating Good Issues

br create --actor "$ACTOR" "Title that explains the task" \
  --type task \
  --priority 1 \
  --description "Detailed description with acceptance criteria"

Include in descriptions:

• Clear scope
• Acceptance criteria
• Dependencies (add separately via br dep add)
• Context for "future self"

Bug issues should include:

• Concise summary
• Reproduction steps
• Expected vs actual behavior
• Environment/context
• Logs or crash pointers

---

Differences from bd (Go beads)

What br Does NOT Support (by design)

• Automatic git commits
• Git hook installation
• Background daemon/RPC
• Dolt backend
• Linear/Jira sync
• Web UI (use bv for TUI)
• Multi-repo sync
• Real-time collaboration

br Troubleshooting

The Doctor Command

br doctor                            # Run full diagnostics

Checks:

• Database integrity
• Schema version
• JSONL sync status
• Configuration validity
• Path permissions

---

Common Errors and Fixes

"Database locked"

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

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

"Issue not found"

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

# Check for similar IDs
br search "keyword" --json

"Prefix mismatch"

# Check your prefix
br config get id.prefix

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

Worktree Error

If you get failed to create worktree: 'main' is already checked out:

git branch beads-sync main
git push -u origin beads-sync
br config set sync.branch beads-sync

Always use a dedicated sync branch that you never check out directly.

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 database seems stale:
br doctor

---

Debugging

# Verbose output
br -v list

# Debug output
br -vv list

# Full trace logs
RUST_LOG=debug br list

---

Quick Health Check

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config list               # Check settings
which br                     # Verify br is installed
br version                   # Check version