Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From beads
Persistent issue tracker for AI agents that survives conversation compaction. Creates, shows, and closes tasks with dependency tracking across sessions.
npx claudepluginhub jmagar/.agents --plugin beadsHow this skill is triggered — by the user, by Claude, or both
Slash command
/beads:beadsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
CLAUDE.mdREADME.mdadr/0001-bd-prime-as-source-of-truth.mdagents/openai.yamlcommands/audit.mdcommands/blocked.mdcommands/close.mdcommands/comments.mdcommands/compact.mdcommands/create.mdcommands/decision.mdcommands/delete.mdcommands/dep.mdcommands/epic.mdcommands/export.mdcommands/import.mdcommands/init.mdcommands/label.mdcommands/list.mdcommands/prime.mdTracks issues as a dependency-aware graph stored in git with bd/br, triages with bv, and converts plans to persistent beads.
Guides using Beads (bd), a distributed git-backed graph issue tracker for managing tasks, tracking dependencies, AI agent workflows, and multi-branch git development.
Guides Beads (bd) usage for git-backed task management, dependency tracking, AI agent workflows, and multi-branch parallel development.
Share bugs, ideas, or general feedback.
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
| bd (persistent) | TodoWrite (ephemeral) |
|---|---|
| Multi-session, dependencies, compaction survival | Single-session linear tasks |
| Dolt-backed team sync | Conversation-scoped |
See BOUNDARIES.md for detailed comparison.
bd --version # Requires v0.60.0+
BEADS_DIR + --stealth for git-free operation)bd init run once (humans do this, not agents)Run bd prime for AI-optimized workflow context (auto-loaded by hooks).
Run bd <command> --help for specific command usage.
Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push
bd ready — Find unblocked workbd show <id> — Get full contextbd update <id> --claim — Claim and start work atomicallybd close <id> --reason "..." — Complete taskbd dolt push — Push to Dolt remote (if configured)Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.
| Error | Fix |
|---|---|
database not found | bd init <prefix> in project root |
not in a git repository | git init first |
disk I/O error (522) | Move .beads/ off cloud-synced filesystem |
| Status updates lag | Use server mode: bd dolt start |
See TROUBLESHOOTING.md for full details.
Track a multi-session feature:
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json # Shows unblocked work
bd update <id> --claim --json # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json
Recover after compaction: bd list --status in_progress --json then bd show <id> --long
Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json
| Feature | CLI | Resource |
|---|---|---|
| Molecules (templates) | bd mol --help | MOLECULES.md |
| Chemistry (pour/wisp) | bd pour, bd wisp | CHEMISTRY_PATTERNS.md |
| Agent beads | bd agent --help | AGENTS.md |
| Async gates | bd gate --help | ASYNC_GATES.md |
| Worktrees | bd worktree --help | WORKTREES.md |
| Category | Files |
|---|---|
| Getting Started | BOUNDARIES.md, CLI_REFERENCE.md (live reference pointers), WORKFLOWS.md |
| Core Concepts | DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md |
| Resilience | RESUMABILITY.md, TROUBLESHOOTING.md |
| Advanced | MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md |
| Reference | STATIC_DATA.md, INTEGRATION_PATTERNS.md |
If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).