beads
Persistent task memory using dependency graphs. For multi-session work that must survive compaction.
When & Why to Use This Skill
Beads is a persistent task management skill designed for Claude agents to maintain long-term context through dependency graphs. It solves the critical issue of 'context loss' during conversation compaction by storing task states, blockers, and progress in an external, git-synced graph, allowing the agent to resume complex workflows seamlessly across multiple sessions.
Use Cases
- Complex Software Engineering: Managing multi-step coding tasks where certain features depend on the completion of others, ensuring the agent remembers the roadmap even after long conversations.
- Persistent Project Tracking: Maintaining a 'source of truth' for project progress that survives LLM context resets or session timeouts, using the 'bd' CLI to sync state with git repositories.
- Dependency Management: Visualizing and navigating task hierarchies to identify unblocked actions, preventing the agent from attempting tasks before their prerequisites are met.
- Cross-Session Collaboration: Resuming work on a long-term research or development project by querying the persistent memory for the last known state and next steps.
| name | beads |
|---|---|
| description | Persistent task memory using dependency graphs. For multi-session work that must survive compaction. |
| compatibility | Requires bd CLI v0.34.0+ and git repository. |
Beads
Graph-based task tracker that survives conversation compaction.
When to Use
Use bd (not TodoWrite) when:
- Context needed across sessions or after compaction
- Tasks have blockers/dependencies
Session Start
bd ready # Find unblocked tasks
bd show <id> # Get context
bd update <id> --status in_progress # Start work
Common Commands
bd create "Title" -p 1 # Create task (priority 0-4)
bd update <id> --notes "Progress" # Add notes (survives compaction)
bd close <id> --reason "Done" # Complete task
bd dep add <child> <parent> # Add dependency
bd sync # Sync with git remote
Notes Format
COMPLETED: Specific deliverables
IN PROGRESS: Current state + next step
BLOCKERS: What's preventing progress
Use bd --help or see references/examples.md for all commands.