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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
namebeads
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 blocks affects 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 priorities
  • references/dependencies.md — Dependency types and usage