Use when tracking work across sessions with Beads issue tracking — guides the bd CLI workflow for creating, managing, and closing issues with dependencies
From interphasenpx claudepluginhub mistakeknot/interagency-marketplace --plugin interphaseThis skill uses the workspace's default tool permissions.
SKILL-compact.mdreferences/CLI_REFERENCE.mdreferences/README.mdreferences/TROUBLESHOOTING.mdDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Beads (bd) is a git-native issue tracker for persistent task tracking across sessions. Issues stored as JSONL in .beads/, synced via git, with hash-based IDs that prevent merge conflicts. Use it for work that spans multiple sessions or has dependencies. For simple single-session tasks, use in-memory TaskCreate instead.
IMPORTANT: The beads database lives at the Interverse monorepo root (/root/projects/Interverse/.beads/), not in individual submodules. Always run bd commands from /root/projects/Interverse/. Submodule .beads/ directories are read-only historical archives — running bd inside a submodule will fail with "no beads database found".
Backend: Dolt (version-controlled SQL with cell-level merge) is the default. .beads/dolt/ contains the database (gitignored). .beads/issues.jsonl is the git-portable sync layer. If Dolt issues surface, rebuild from JSONL: bd doctor --fix --source=jsonl.
Use Beads (bd) when... | Use TaskCreate when... |
|---|---|
| Work spans multiple sessions | Single session task |
| Tasks have dependencies | Independent tasks |
| Need persistent tracking | Temporary tracking is fine |
| Collaborating across agents | Solo execution |
| Want git-synced state | Ephemeral state is fine |
bd ready # Show issues ready to work (no blockers)
bd list --status=open # All open issues
bd list --status=in_progress # Active work
bd blocked # Show all blocked issues
bd show <id> # Detailed view with dependencies
bd create --title="..." --type=task|bug|feature|epic|decision --priority=2
Priority scale: 0-4 or P0-P4 (0=critical, 2=medium, 4=backlog). NOT "high"/"medium"/"low".
Use dot notation for epic → task → sub-task hierarchies:
bd create --title="Auth overhaul" --type=feature --priority=1
# Creates bd-a3f8
bd create --title="JWT middleware" --parent=bd-a3f8 --priority=2
# Creates bd-a3f8.1
bd create --title="Token refresh logic" --parent=bd-a3f8.1 --priority=2
# Creates bd-a3f8.1.1
bd update <id> --claim # Atomically claim (fails if already claimed)
bd update <id> --status=in_progress # Soft claim (no collision detection — prefer --claim)
bd update <id> --assignee=username # Assign
bd close <id> # Mark complete
bd close <id1> <id2> ... # Close multiple at once
bd close <id> --reason="explanation" # Close with reason
bd dep add <issue> <depends-on> # issue depends on depends-on
bd blocked # Show all blocked issues
bd sync # Compatibility sync step (0.50.x syncs, 0.51+ no-op)
bd doctor # Health/status check
Local-only tracking, nothing committed to the main repo:
bd init --stealth
Use for: experimental planning, personal task tracking, throwaway exploration.
Routes planning to a separate repo, keeping experimental work out of PRs:
bd init --contributor
Planning state stored in ~/.beads-planning instead of the project's .beads/.
Full read-write access. Auto-detected via SSH or authenticated HTTPS:
git config beads.role maintainer # Force maintainer mode
bv provides AI-friendly analytics on your task graph:
bv # Open viewer with PageRank, critical path, parallel tracks
Surfaces: task recommendations, execution order, blocking chains, parallel execution opportunities. Use before dispatching parallel agents to identify independent work streams.
Closed tasks are semantically summarized to preserve context while reducing token cost. Beads handles this automatically — old completed tasks are compacted so agents get the gist without reading full histories.
Beads databases grow over time. Keep them healthy:
bd doctor --fix --yes — runs daily via systemd timer; fixes common issues automaticallybd admin cleanup --older-than 30 --force — prunes closed issues older than 30 days (always recoverable from git history)bd sync — compatibility sync step for mixed beads versions (0.50.x syncs, 0.51+ no-op)bd upgrade periodically to get latest fixes (not automated — requires binary install)If you see "issues.jsonl too large" or agents failing to parse beads, run bd admin cleanup --older-than 7 --force for aggressive cleanup.
The daily hygiene runs at 6:15 AM Pacific across all projects in /root/projects/. Check logs: journalctl -u clavain-beads-hygiene.service --since today
CRITICAL: Before saying "done" or "complete", run this checklist:
git status # Check what changed
git add <files> # Stage code changes
git commit -m "..." # Commit code
bd backup # Flush state to JSONL (survives Dolt crashes)
bash .beads/push.sh # Push Dolt to remote
git push # Push to remote
NEVER skip this. bd backup writes fresh JSONL that recovery reads — without it, closes are lost on the next Dolt crash. Work is not done until pushed.
Close + sync shortcut: bash .beads/close-and-sync.sh <id> [--reason="..."] — closes, backs up, and pushes in one step.
Starting work:
bd ready # Find available work
bd show <id> # Review details
bd update <id> --claim # Atomically claim it
Completing work:
bd close <id1> <id2> ... # Close completed issues
bd backup # Flush to JSONL immediately
bash .beads/push.sh # Push to Dolt remote
Or in one step: bash .beads/close-and-sync.sh <id1> <id2> ... [--reason="..."]
Creating dependent work:
bd create --title="Implement feature X" --type=feature --priority=2
bd create --title="Write tests for X" --type=task --priority=2
bd dep add <tests-id> <feature-id> # Tests depend on feature
After batch creation (reviews, audits, planning):
Whenever you create 5+ beads in a session — especially from reviews, audits, or brainstorming — run a consolidation pass before moving on:
bd list --status=open # Review the full backlog
Look for:
--reason="absorbed into <parent-id>"bd dep add# Absorb child into parent
bd update <parent-id> --description="...add child's criteria..."
bd close <child-id> --force --reason="absorbed into <parent-id>"
# Add missing dependency
bd dep add <downstream-id> <upstream-id>
This typically reduces batch-created backlogs by 30-40% and prevents fragmented work.
Pairs with:
file-todos — Beads for cross-session, file-todos for within-sessionlanding-a-change — Session close protocol ensures beads are syncedtriage command — Categorize and prioritize beads issuesdispatching-parallel-agents — Use bv to identify independent work streams before dispatching