---

name: beads description: "Issue tracking with Beads (bd CLI). Use when commands need to create, query, or update issues." allowed-tools: Bash

Beads Issue Tracker

When to Use

• Creating or updating issues
• Querying ready/blocked tasks
• Managing dependencies
• Closing completed work

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

Copybd show <id> --json

Returns full issue data: title, description, status, type, priority, dependencies.

Check If Issue Exists

Copybd show <id>

Exit code 0 = exists, non-zero = not found.

Create Issue

Copybd create --title "Title" --type task --priority 2 --description "Description" --json

Creates new issue. Use --parent <epic-id> for subtasks.

Update Status

Copybd update <id> --status in_progress --json

Valid statuses: open, in_progress, closed.

Add Dependency

Copybd dep add <blocked-id> <blocker-id> --type blocks

Makes blocker-id block blocked-id. Only blocks affects ready state.

Get Dependency Tree

Copybd dep tree <id>

Shows issue hierarchy and blocking relationships.

Find Ready Tasks

Copybd ready --json

Lists tasks with no unresolved blockers.

Find Blocked Tasks

Copybd blocked --json

Lists tasks waiting on blockers.

Close Issue

Copybd close <id> --reason "Done: summary" --json

Marks issue as closed with resolution reason.

List Issues

Copybd list --status open --json

Filter by status, type, priority.

Sync

Copybd sync

Synchronizes local state with remote.

Quick Reference

References

• references/types.md — Issue types and priorities
• references/dependencies.md — Dependency types and usage