beads

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 --claim --json # Claim and start bd close --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).Weekly Installs332Repositorysteveyegge/beadsGitHub Stars19.2KFirst SeenJan 30, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled onopencode324codex320github-copilot318gemini-cli317amp311kimi-cli309