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
- Task tools (TaskCreate/TaskUpdate/TaskList): Single-session tasks, status tracking, 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 initrun once (humans do this, not agents)
Examples
Skill Loading from $vibe
User says: $vibe
What happens:
- Agent loads beads skill automatically via dependency
- Agent calls
bd show <id>to read issue metadata - Agent links validation findings to the issue being checked
- 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:
- Agent loads beads skill to understand issue structure
- Agent calls
bd show ag-xyz-123to read issue body - Agent checks dependencies with bd output
- Agent closes issue with
bd close ag-xyz-123after completion
Result: Issue lifecycle managed automatically during implementation.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| bd command not found | bd CLI not installed or not in PATH | Install bd: brew install bd or check PATH |
| "not a git repository" error | bd requires git repo, current dir not initialized | Run git init or navigate to git repo root |
| "beads not initialized" error | .beads/ directory missing | Human runs bd init --prefix <prefix> once |
| Issue ID format errors | Wrong prefix or malformed ID | Check rigs.json for correct prefix, follow <prefix>-<tag>-<num> format |
Reference Documents
- references/ANTI_PATTERNS.md
- references/BOUNDARIES.md
- references/CLI_REFERENCE.md
- references/DEPENDENCIES.md
- references/INTEGRATION_PATTERNS.md
- references/ISSUE_CREATION.md
- references/MOLECULES.md
- references/PATTERNS.md
- references/RESUMABILITY.md
- references/ROUTING.md
- references/STATIC_DATA.md
- references/TROUBLESHOOTING.md
- references/WORKFLOWS.md
Local Resources
references/
- references/ANTI_PATTERNS.md
- references/BOUNDARIES.md
- references/CLI_REFERENCE.md
- references/DEPENDENCIES.md
- references/INTEGRATION_PATTERNS.md
- references/ISSUE_CREATION.md
- references/MOLECULES.md
- references/PATTERNS.md
- references/RESUMABILITY.md
- references/ROUTING.md
- references/STATIC_DATA.md
- references/TROUBLESHOOTING.md
- references/WORKFLOWS.md
scripts/
scripts/validate.sh