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 --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 — Get full context bd update --claim — Claim and start work atomically Add notes as you work (critical for compaction survival) bd close --reason "..." — Complete task bd dolt push — Push to Dolt remote (if configured) Output Append --json to any command for structured output. Use bd show --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred. Error Handling Error Fix database not found bd init 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 --long Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from: --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 ).