beads

Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides persistent memory that survives conversation compaction. Use when work spans multiple sessions, has complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or "update status".

⭐8stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025⬇️4downloads

When & Why to Use This Skill

Beads is a Git-backed persistent memory and issue tracking system designed for AI agents to manage complex, multi-session workflows. It solves the critical problem of context loss during conversation compaction by providing a graph-based dependency tracker that ensures task progress, blockers, and historical notes remain accessible across different sessions and long-term projects.

Use Cases

  • Managing long-term software engineering projects where tasks span multiple days and require tracking complex dependencies and blockers.
  • Ensuring context recovery after conversation compaction or session resets, allowing the AI to resume work exactly where it left off.
  • Collaborative task management where agent-generated issues and progress updates are synced via Git for team transparency and synchronization.
  • Executing multi-step research or exploratory workflows that involve fuzzy boundaries and require a structured graph to visualize what is 'ready' to work on.
  • Maintaining a persistent 'source of truth' for project status that survives beyond the immediate chat history.
namebeads
description>
allowed-tools"Read,Bash(bd:*)"
version"0.43.0"
author"Steve Yegge <https://github.com/steveyegge>"
license"MIT"

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

bd (persistent) TodoWrite (ephemeral)
Multi-session work Single-session tasks
Complex dependencies Linear execution
Survives compaction Conversation-scoped
Git-backed, team sync Local to session

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:

  • Work spans multiple sessions or days
  • Tasks have dependencies or blockers
  • Need to survive conversation compaction
  • Exploratory/research work with fuzzy boundaries
  • Collaboration with team (git sync)

When to use TodoWrite:

  • Single-session linear tasks
  • Simple checklist for immediate work
  • All context is in current conversation
  • Will complete within current session

Prerequisites

bd --version  # Requires v0.34.0+
  • bd CLI installed and in PATH
  • Git repository (bd requires git for sync)
  • 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 sync

Session Protocol

  1. bd ready — Find unblocked work
  2. bd show <id> — Get full context
  3. bd update <id> --status in_progress — Start work
  4. Add notes as you work (critical for compaction survival)
  5. bd close <id> --reason "..." — Complete task
  6. bd sync — Persist to git (always run at session end)

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

Resource Content
BOUNDARIES.md bd vs TodoWrite detailed comparison
CLI_REFERENCE.md Complete command syntax
DEPENDENCIES.md Dependency system deep dive
INTEGRATION_PATTERNS.md TodoWrite and tool integration
ISSUE_CREATION.md When and how to create issues
MOLECULES.md Proto definitions, component labels
PATTERNS.md Common usage patterns
RESUMABILITY.md Compaction survival guide
STATIC_DATA.md Database schema reference
TROUBLESHOOTING.md Error handling and fixes
WORKFLOWS.md Step-by-step workflow patterns
AGENTS.md Agent bead tracking (v0.40+)
ASYNC_GATES.md Human-in-the-loop gates
CHEMISTRY_PATTERNS.md Mol vs Wisp decision tree
WORKTREES.md Parallel development patterns

Full Documentation