Beads Br
Productivitybeads-brBeads Br is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Local-first issue tracker (beads_rust) for AI agents. Use when tracking tasks, managing dependencies, finding ready work, or syncing issues to git via JSONL.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/productivity/beads-br/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/beads-br, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 |
Private-ledger repos — the persist_intent port contract
Some repos declare a private bead ledger separated from the public source tree. The agentops repo is the canonical case; an agent that loads only this skill (without the repo CLAUDE.md) must still honor these invariants:
| Invariant | Rule |
|---|---|
| Indirection | Invoke as BEADS_DIR=$PWD/_beads br <cmd> — the ledger lives at _beads/, not .beads/ (legacy .beads/ holds retired tracker config; br init there would clobber it). |
| Private repo | _beads/ is its own git repository (separate remote). Sync = git -C _beads push. |
| Never leak | never run git add _beads in the host repo — bead bodies carry private context; the host repo is public and gitignores the ledger. |
| bd is retired | because the bd/Dolt remote-server lane was retired (2026-06-11) — do not run bd in a br repo; it appears only in explicitly-marked legacy notes. |
| Prefix filter | to prevent cross-project leakage in shared DBs, filter queries by the repo's issue prefix (e.g. ag-) before trusting br ready output. |
This section is the persist_intent port contract: the skill that persists
intent owns the rules that keep that intent private and uncorrupted.
Quick Workflow
# 1. Find work
br ready --json
# 2. Claim it
br update bd-abc123 --status in_progress
# 3. Do work...
# 4. Complete
br close bd-abc123 --reason "Implemented X"
# 5. Sync to git (EXPLICIT!)
br sync --flush-only
git add .beads/ && git commit -m "feat: X (bd-abc123)"
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)
# 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="bd-123")
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
# Work...
br close bd-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
Issue-Lifecycle Discipline
Folded from the retired beads umbrella (ag-ez7y6) — operating doctrine, not
the command surface above. These keep the tracker graph honest across sessions:
- Live reads are authoritative. Treat live
br show/br ready/br listoutput as the source of truth for current tracker state. Do NOT treat the exportedissues.jsonlas the primary decision source when livebrdata is available — the JSONL is a git-friendly export artifact, refreshed onbr sync --flush-only. - Scoped closure proof on every close.
br close <id> --reasonmust name the touched files (or explicit no-file evidence artifact), the validation command(s) run, and the parent-reconciliation outcome. Never close a child bead with a generic reason like "done" or "implemented". - Reconcile the parent in the same session. After closing or materially updating a child bead, reconcile the open parent: update stale "remaining gap" notes immediately, and close the parent when the child resolved its last real gap.
- Narrow the umbrella issue before implementing. If
br readysurfaces a broad umbrella bead, do not implement against vague parent wording — first narrow the remaining gap into an execution-ready child bead, land the child, then reconcile the parent. - Normalize stale queue items instead of skipping them. Rewrite broad or partially-absorbed beads to the actual remaining gap rather than silently passing over them.
Anti-Patterns
- Running
br syncwithout--flush-onlyor--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 |