How do I install the Beads skill?

Run npx skillmds@latest add arustydev/beads in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Beads safe to use?

SkillMD's automated safety review verdict for this skill is PASS. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Beads?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Beads free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

aRustyDev (@arustydev) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Beads by arustydev — Agent Skill

Name: Beads
Rating: 4.2 (5 reviews)
Author: aRustyDev

Beads

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.

aRustyDev Updated Aug 19, 2026 8 repo stars

File contents

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 + --stealth for git-free operation)
Initialization: bd init run 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 work
bd show <id> — Get full context
bd update <id> --claim — Claim and start work atomically
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete task
bd 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, 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).

---name: beadsdescription: 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.license: MIT---# Beads - Persistent Task Memory for AI AgentsGraph-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](${CLAUDE_SKILL_DIR}/resources/BOUNDARIES.md) for detailed comparison.## Prerequisites```bashbd --version # Requires v0.60.0+```- **bd CLI** installed and in PATH- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)- **Initialization**: `bd init` run 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 Protocol1. `bd ready` — Find unblocked work2. `bd show <id>` — Get full context3. `bd update <id> --claim` — Claim and start work atomically4. Add notes as you work (critical for compaction survival)5. `bd close <id> --reason "..."` — Complete task6. `bd dolt push` — Push to Dolt remote (if configured)## OutputAppend `--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](${CLAUDE_SKILL_DIR}/resources/TROUBLESHOOTING.md) for full details.## Examples**Track a multi-session feature:**```bashbd create "OAuth integration" -t epic -p 1 --jsonbd create "Token storage" -t task --deps blocks:oauth-id --jsonbd ready --json # Shows unblocked workbd update <id> --claim --json # Claim and startbd 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](${CLAUDE_SKILL_DIR}/resources/MOLECULES.md) || Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](${CLAUDE_SKILL_DIR}/resources/CHEMISTRY_PATTERNS.md) || Agent beads | `bd agent --help` | [AGENTS.md](${CLAUDE_SKILL_DIR}/resources/AGENTS.md) || Async gates | `bd gate --help` | [ASYNC_GATES.md](${CLAUDE_SKILL_DIR}/resources/ASYNC_GATES.md) || Worktrees | `bd worktree --help` | [WORKTREES.md](${CLAUDE_SKILL_DIR}/resources/WORKTREES.md) |## Resources| Category | Files ||----------|-------|| **Getting Started** | [BOUNDARIES.md](${CLAUDE_SKILL_DIR}/resources/BOUNDARIES.md), [CLI_REFERENCE.md](${CLAUDE_SKILL_DIR}/resources/CLI_REFERENCE.md), [WORKFLOWS.md](${CLAUDE_SKILL_DIR}/resources/WORKFLOWS.md) || **Core Concepts** | [DEPENDENCIES.md](${CLAUDE_SKILL_DIR}/resources/DEPENDENCIES.md), [ISSUE_CREATION.md](${CLAUDE_SKILL_DIR}/resources/ISSUE_CREATION.md), [PATTERNS.md](${CLAUDE_SKILL_DIR}/resources/PATTERNS.md) || **Resilience** | [RESUMABILITY.md](${CLAUDE_SKILL_DIR}/resources/RESUMABILITY.md), [TROUBLESHOOTING.md](${CLAUDE_SKILL_DIR}/resources/TROUBLESHOOTING.md) || **Advanced** | [MOLECULES.md](${CLAUDE_SKILL_DIR}/resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](${CLAUDE_SKILL_DIR}/resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](${CLAUDE_SKILL_DIR}/resources/AGENTS.md), [ASYNC_GATES.md](${CLAUDE_SKILL_DIR}/resources/ASYNC_GATES.md), [WORKTREES.md](${CLAUDE_SKILL_DIR}/resources/WORKTREES.md) || **Reference** | [STATIC_DATA.md](${CLAUDE_SKILL_DIR}/resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](${CLAUDE_SKILL_DIR}/resources/INTEGRATION_PATTERNS.md) |## ValidationIf `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](${CLAUDE_SKILL_DIR}/adr/0001-bd-prime-as-source-of-truth.md)).

Frequently asked questions