beads

r0man's avatarfrom r0man

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".

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025⬇️1downloads

When & Why to Use This Skill

Beads is a Git-backed persistent task memory and graph-based issue tracker designed specifically for AI agents. It solves the critical problem of context loss during conversation compaction and session timeouts by providing a stable, multi-session framework. By using dependency graphs and persistent storage, it ensures that complex project states, blockers, and task histories survive beyond a single chat window, enabling seamless long-term agentic workflows.

Use Cases

  • Managing complex software development projects where tasks span multiple days and require tracking intricate dependencies and blockers.
  • Maintaining project continuity and context recovery after an AI conversation reaches its token limit and undergoes compaction.
  • Collaborative AI-human workflows that require syncing task statuses and notes via Git for team-wide visibility and persistence.
  • Executing long-running research or exploratory tasks that involve fuzzy boundaries and require a structured way to track 'ready' vs 'blocked' work.
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