beads

This skill teaches effective use of beads (bd), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.

Getting Started

First, check if beads is available and initialized:

# Check if bd is installed
bd version

# Check if current project has beads initialized
bd status

If bd is not installed, ask the user which installation method they prefer:

• npm: npm install -g @beads/bd
• Homebrew: brew install beads (macOS)
• Go: go install github.com/steveyegge/beads/cmd/bd@latest

Do not install without user confirmation, as these are global system packages.

If not initialized in the project, run:

bd init

For personal use on shared projects (won't commit to repo):

bd init --stealth

For contributors on forked repos (routes to separate planning repo):

bd init --contributor

Essential Commands

Command	Purpose
bd ready	List tasks with no open blockers (what to work on next)
bd create "Title" -p 1	Create a task (priority 0-3, lower = higher priority)
bd show <id>	View task details and dependencies
bd list	List all open issues
bd close <id>	Mark task as complete
bd update <id> --status in_progress	Update task status
bd dep add <child> <parent>	Create dependency (child blocked by parent)
bd sync	Force immediate sync to git

Always use --json flag for machine-readable output when parsing results.

Task Hierarchy

Beads supports hierarchical IDs for organizing work:

• bd-a3f8 — Epic (large feature)
• bd-a3f8.1 — Task under epic
• bd-a3f8.1.1 — Sub-task

Create hierarchical tasks:

bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8

Session Workflow

Starting a Session

# See what's ready to work on
bd ready --json

# Pick a task and mark it in progress
bd update <id> --status in_progress

# View full details
bd show <id> --json