beads
Track complex, multi-session work with dependency graphs using beads issue tracker. Use when work spans multiple sessions, has complex dependencies, or requires persistent context across compaction cycles. For simple single-session linear tasks, TodoWrite remains appropriate.
When & Why to Use This Skill
The Beads skill is a robust issue tracking and dependency management tool designed for Claude agents to handle complex, multi-session workflows. By utilizing dependency graphs and persistent state, it allows agents to manage tasks, bugs, and epics effectively, ensuring continuity and organization even when work spans across multiple sessions or requires intricate task sequencing. It serves as a sophisticated alternative to simple to-do lists for high-stakes, long-term engineering and research projects.
Use Cases
- Complex Software Development: Track feature implementations and bug fixes where certain tasks must be completed before others can begin, using the 'blocks' dependency feature.
- Multi-Session Continuity: Maintain a persistent record of project progress and pending items across different AI interaction cycles or context compaction events to prevent loss of context.
- Hierarchical Task Organization: Break down large-scale 'Epics' into granular subtasks and chores, assigning priorities (0-4) and tracking their status from 'open' to 'closed'.
- Bottleneck Identification: Use the 'ready' and 'blocked' commands to visualize the dependency tree and identify which critical tasks are currently preventing project advancement.
| name | beads |
|---|---|
| description | "Issue tracking with Beads (bd CLI). Use when commands need to create, query, update, or close issues, or manage dependencies." |
Beads Issue Tracker
Core Concepts
- bd ready — tasks with no blockers
- Status: open → in_progress → closed
- Types: task, bug, feature, epic, chore
- Priority: 0 (critical) → 4 (low), default 2
- Dependencies: only
blocksaffects ready
Operations
Get Issue Details
bd show <id> --json
Returns full issue data: title, description, status, type, priority, dependencies.
Check If Issue Exists
bd show <id>
Exit code 0 = exists, non-zero = not found.
Create Issue
bd create --title "Title" --type task --priority 2 --description "Description" --json
Creates new issue. Use --parent <epic-id> for subtasks.
Update Status
bd update <id> --status in_progress --json
Valid statuses: open, in_progress, closed.
Add Dependency
bd dep add <blocked-id> <blocker-id> --type blocks
Makes blocker-id block blocked-id. Only blocks affects ready state.
Get Dependency Tree
bd dep tree <id>
Shows issue hierarchy and blocking relationships.
Find Ready Tasks
bd ready --json
Lists tasks with no unresolved blockers.
Find Blocked Tasks
bd blocked --json
Lists tasks waiting on blockers.
Close Issue
bd close <id> --reason "Done: summary" --json
Marks issue as closed with resolution reason.
List Issues
bd list --status open --json
Filter by status, type, priority.
Sync
bd sync
Synchronizes local state with remote.
Quick Reference
| Action | Command |
|---|---|
| Show issue | bd show <id> --json |
| Create issue | bd create --title "..." --type task --json |
| Update status | bd update <id> --status in_progress |
| Add blocker | bd dep add <blocked> <blocker> --type blocks |
| Ready tasks | bd ready --json |
| Close issue | bd close <id> --reason "..." |
References
references/types.md— Issue types and prioritiesreferences/dependencies.md— Dependency types and usage