Agent skill

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.

View SKILL.md on GitHub Repository
Stars 20,631
Forks 1,383

Install this agent skill to your Project

npx add-skill https://github.com/gastownhall/beads/tree/main/claude-plugin/skills/beads

SKILL.md

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

bash
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:

bash
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).

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

gastownhall/beads

handoff

Hand off to a fresh Claude session. Use when context is full, you've finished a logical chunk of work, or need a fresh perspective. Work continues from hook.

20,631 1,383
Explore
davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298
Explore
davila7/claude-code-templates

openrlhf-training

High-performance RLHF framework with Ray+vLLM acceleration. Use for PPO, GRPO, RLOO, DPO training of large models (7B-70B+). Built on Ray, vLLM, ZeRO-3. 2× faster than DeepSpeedChat with distributed architecture and GPU resource sharing.

23,776 2,298
Explore
davila7/claude-code-templates

gguf-quantization

GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements.

23,776 2,298
Explore
davila7/claude-code-templates

Claude Code Guide

Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent.

23,776 2,298
Explore
davila7/claude-code-templates

qdrant-vector-search

High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.

23,776 2,298
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results