A Git-backed issue tracker that maintains persistent context and dependency tracking across coding sessions.
Install
mkdir -p .claude/skills/beads && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/4442" && unzip -o skill.zip -d .claude/skills/beads && rm skill.zipInstalls to .claude/skills/beads
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.Key capabilities
- →Track tasks across multiple sessions
- →Map dependencies between sub-tasks
- →Recover context after conversation compaction
- →Manage task status and lifecycle
- →Push state to Dolt remote
How it works
It uses a Dolt-powered graph database to store task state persistently, allowing the agent to query and update work status across different conversation sessions.
Inputs & outputs
When to use beads
- →Track multi-session development tasks
- →Manage dependency mapping between sub-tasks
- →Restore context after session compaction
- →Log blockers and technical notes
About this skill
Beads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
bd vs TodoWrite
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.
Prerequisites
bd --version # Requires v0.60.0+
- bd CLI installed and in PATH
- Git repository (optional — use
BEADS_DIR+--stealthfor git-free operation) - Initialization:
bd initrun once (humans do this, not agents)
CLI Reference
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
Session Protocol
bd ready— Find unblocked workbd show <id>— Get full contextbd update <id> --claim— Claim and start work atomically- Add notes as you work (critical for compaction survival)
bd close <id> --reason "..."— Complete taskbd dolt push— Push to Dolt remote (if configured)
Output
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 Handling
| 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.
Examples
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
Advanced Features
| 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 |
Resources
| 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 |
Validation
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).
When not to use it
- →Short-lived, single-session tasks
- →Projects not requiring persistent memory
Prerequisites
Limitations
- →Requires manual initialization with bd init
- →Not suitable for cloud-synced filesystems due to I/O errors
How it compares
It provides persistent, graph-based task tracking that survives AI conversation memory resets, unlike standard ephemeral todo lists.
Compared to similar skills
beads side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| beads (this skill) | 1 | 1mo | Review | Intermediate |
| tmux | 20 | 2mo | Review | Intermediate |
| jira | 11 | 6mo | No flags | Beginner |
| triaging-issues | 5 | 2mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
tmux
openclaw
Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
jira
davila7
Use when the user mentions Jira issues (e.g., "PROJ-123"), asks about tickets, wants to create/view/update issues, check sprint status, or manage their Jira workflow. Triggers on keywords like "jira", "issue", "ticket", "sprint", "backlog", or issue key patterns.
triaging-issues
pytorch
Triages GitHub issues by routing to oncall teams, applying labels, and closing questions. Use when processing new PyTorch issues or when asked to triage an issue.
file-manager
Xxiii8322766509
文件管理技能。用于创建、移动、复制、删除文件和文件夹，整理目录结构。当用户需要管理文件、整理文件夹或批量处理文件时使用。
openspec-archive-change
studyzy
归档实验性工作流中已完成的变更。当用户想要在实现完成后最终确定并归档变更时使用。
slash-commands
parcadei
Create and use Claude Code slash commands - quick prompts, bash execution, file references