beads-br

name	beads-br
description	Beads Rust issue tracker (br). Use when tracking tasks, managing dependencies, finding ready work, or syncing issues to git via JSONL.

beads-br — Beads Rust Issue Tracker

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

Critical Rules for Agents

Rule	Why
ALWAYS use --json	Structured output for parsing
NEVER run bare bv	Blocks session in TUI mode
Sync is EXPLICIT	br sync --flush-only after changes
Git is YOUR job	br only touches .beads/ directory
No cycles allowed	br dep cycles must return empty

Quick Workflow

# 1. Find work
br ready --json

# NOTE (br 0.1.8): `br ready` is currently broken in some workspaces due to an
# internal SQL bug. Workaround: use `bv --recipe actionable --robot-plan` (or
# `bv --robot-triage`) + `br list --json`.

# 2. Claim it
br update <id> --status in_progress

# 3. Do work...

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

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

Essential Commands

# Lifecycle
br init                              # Initialize .beads/
br create "Title" -p 1 -t task       # Create (priority 0-4)
br update <id> --status in_progress  # Claim work
br close <id> --reason "Done"        # Complete
br reopen <id>                       # Reopen if needed

# Querying (always use --json for agents)
br ready --json                      # Actionable work (not blocked)
br list --json                       # All issues
br blocked --json                    # What's blocked
br search "keyword"                  # Full-text search
br show <id> --json                  # Issue details

# Dependencies
br dep add <child> <parent>          # child depends on parent
br dep cycles                        # MUST be empty!
br dep tree <id>                     # Visualize dependencies

# Sync (EXPLICIT - never automatic)
br sync --flush-only                 # DB → JSONL (before git commit)
br sync --import-only                # JSONL → DB (after git pull)

# Skills sync status (canonical vs global skills)
br skills sync-status --json         # JSON summary of drift
br skills sync-status --verbose      # Per-skill details

# System
br doctor                            # Health check
br config list                       # Show configuration

Priority Scale

Priority	Meaning
0	Critical
1	High
2	Medium (default)
3	Low
4	Backlog

bv Integration

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

# Always use --robot-* flags:
bv --robot-next                      # Single top pick
bv --robot-triage                    # Full triage
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights | jq '.Cycles'   # Check graph health

Agent Mail Coordination

Use bead ID as thread_id for multi-agent coordination:

file_reservation_paths(..., reason="br-123")
send_message(..., thread_id="br-123", subject="[br-123] Starting...")
# Work...
br close br-123 --reason "Completed"
release_file_reservations(...)

Session Ending Pattern

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # Verify clean

Anti-Patterns

• Running br sync without --flush-only or --import-only
• Forgetting sync before git commit
• Creating circular dependencies
• Running bare bv
• Assuming auto-commit behavior

Storage

.beads/
├── beads.db        # SQLite (primary)
├── issues.jsonl    # Git-friendly export
└── config.yaml     # Optional config

Troubleshooting

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config list               # Check settings

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

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

---

References

Topic	File
Full command reference	COMMANDS.md
Configuration details	CONFIG.md
Troubleshooting guide	TROUBLESHOOTING.md
Multi-agent patterns	INTEGRATION.md