Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction.

Overview

bd (beads) replaces markdown task lists with a dependency-aware graph stored in git.

Key Distinction:

• bd: Multi-session work, dependencies, survives compaction, git-backed
• TodoWrite: Single-session tasks, linear execution, conversation-scoped

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Prerequisites

• bd CLI: Version 0.34.0+ installed and in PATH
• Git Repository: Current directory must be a git repo
• Initialization: bd init run once (humans do this, not agents)

Examples

Skill Loading from /vibe

User says: /vibe

What happens:

1. Agent loads beads skill automatically via dependency
2. Agent calls bd show <id> to read issue metadata
3. Agent links validation findings to the issue being checked
4. Output references issue ID in validation report

Result: Validation report includes issue context, no manual bd lookups needed.

Skill Loading from /implement

User says: /implement ag-xyz-123

What happens:

1. Agent loads beads skill to understand issue structure
2. Agent calls bd show ag-xyz-123 to read issue body
3. Agent checks dependencies with bd output
4. Agent closes issue with bd close ag-xyz-123 after completion

Result: Issue lifecycle managed automatically during implementation.

Troubleshooting