name	beads-cli
description	Task tracking with the bd (Beads) CLI. Use when creating tasks, claiming work, closing beads, managing dependencies, or when the user mentions "beads", "bd", or "tasks".

Beads CLI (bd)

Task tracking across sessions. All issue tracking goes through bd.

When This Applies

Signal	Action
Need to create a task	`bd create`
Looking for work	`bd ready --json`
Claiming a task	`bd update --status in_progress`
Finishing a task	`bd close`
Managing dependencies	`bd dep add/tree`

Core Workflow

# Finding work
bd ready --json                    # Unblocked tasks ready for work
bd blocked                         # Tasks waiting on dependencies
bd list                            # All tasks

# Task lifecycle
bd create "Title" -t bug -p 1      # Create with type, priority
bd update bd-42 --status in_progress --assignee YOUR_NAME  # Claim
bd close bd-42 --reason "Completed: summary"               # Complete

# Viewing
bd show bd-42                      # Full task details
bd info                            # Project summary

Dependencies

bd dep add bd-child bd-blocker --type blocks        # Child blocked by blocker
bd dep add bd-a bd-b --type related                 # Related tasks
bd dep add bd-child bd-parent --type parent-child   # Hierarchy
bd dep add bd-new bd-old --type discovered-from     # Found during work
bd dep tree bd-42                                   # Visualize dependencies
bd dep cycles                                       # Find circular deps

Task Types and Priority

Type	Use For
`bug`	Defects, errors
`feature`	New functionality
`task`	General work items
`epic`	Parent/container beads
`chore`	Maintenance, cleanup

Priority	Meaning
`0`	Critical (do first)
`1`	High
`2`	Normal
`3`	Low
`4`	Backlog

Child Beads

Hierarchical IDs: bd-a1b2.1, bd-a1b2.3.1

bd create "Sub-task" --parent bd-123 -p 1

Claiming Protocol (Multi-Agent)

CRITICAL: Always claim parent AND all sub-beads together.

bd update bd-123 --status in_progress --assignee YOUR_NAME
bd update bd-123.1 --status in_progress --assignee YOUR_NAME
bd update bd-123.2 --status in_progress --assignee YOUR_NAME

Why: If you only claim parent, other agents see sub-beads as "ready" → CONFLICT.

Closing Protocol

CRITICAL: Close sub-beads first, then parent.

bd close bd-123.1 --reason "Completed: implemented X"
bd close bd-123.2 --reason "Completed: added tests"
bd close bd-123 --reason "Completed: full feature done"

Maintenance

bd doctor                          # Health check
bd doctor --fix                    # Auto-fix issues
bd compact --analyze --json        # Analyze for compaction
bd --readonly list                 # Safe read-only mode

Key Rules

Rule	Why
Always commit `.beads/` with code	Keeps state in sync
Never edit `.beads/*.jsonl` directly	Use `bd` commands only
Always set `--assignee` when claiming	Prevents conflicts
Never use other TODO systems	Beads is authoritative

Quick Reference

bd ready --json          # What's available?
bd update ID --status in_progress --assignee NAME   # Claim
bd close ID --reason "..."   # Complete
bd create "Title" -t TYPE -p PRIORITY   # Create
bd dep add CHILD BLOCKER --type blocks   # Add dependency
bd doctor --fix          # Health check

beads-cli

Install Skill

SKILL.md