Agent-Skills.md

Agent Skills: Beads - Persistent Task Memory for AI Agents

>

UncategorizedID: steveyegge/beads/beads

Repository

steveyegge/beads
gastownhallLicense: MIT
20,0471,326

Install this agent skill to your local

pnpm dlx add-skill https://github.com/gastownhall/beads/tree/HEAD/claude-plugin/skills/beads

Skill Files

Browse the full folder contents for beads.

Download Skill

Loading file tree…

claude-plugin/skills/beads/SKILL.md

Skill Metadata

Name
beads
Description
>

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

  1. bd ready — Find unblocked work
  2. bd show <id> — Get full context
  3. bd update <id> --claim — Claim and start work atomically
  4. Add notes as you work (critical for compaction survival)
  5. bd close <id> --reason "..." — Complete task
  6. 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).