bd ready

Usage

bd ready [flags]

Description

Show ready work: open issues with no active blocking dependencies. This is the primary command for finding work that can be started immediately. Excludes in_progress, blocked, deferred, and hooked issues. Uses blocker-aware semantics to find truly claimable work.

Note: bd list --ready is NOT equivalent - it only filters by status=open without checking blockers.

Parameters

Filtering

--limit

integer

default:"10"

Maximum issues to show

--priority

integer

Filter by priority (0-4)

--assignee

string

Filter by assignee

--unassigned

boolean

Show only unassigned issues

--type

string

Filter by issue type: task, bug, feature, epic, decision, merge-request. Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision

--label

string[]

Filter by labels (AND: must have ALL). Can combine with --label-any.

--label-any

string[]

Filter by labels (OR: must have AT LEAST ONE). Can combine with --label.

--parent

string

Filter to descendants of this bead/epic

--mol-type

string

Filter by molecule type: swarm, patrol, or work

Molecule Mode

--mol

string

Filter to steps within a specific molecule

--gated

boolean

Find molecules ready for gate-resume dispatch

Sorting

--sort

string

default:"priority"

Sort policy: priority (default), hybrid, oldest

Display

--pretty

boolean

default:"true"

Display issues in a tree format with status/priority symbols

--plain

boolean

Display issues as a plain numbered list

Advanced

--include-deferred

boolean

Include issues with future defer_until timestamps

--include-ephemeral

boolean

Include ephemeral issues (wisps) in results

--rig

string

Query a different rig’s database (e.g., --rig gastown, --rig gt-, --rig gt)

--metadata-field

string[]

Filter by metadata field (format: key=value, repeatable)

--has-metadata-key

string

Filter issues that have this metadata key set

Output

--json

boolean

Output JSON for agent use

Examples

Basic Usage

# Show top 10 ready issues by priority
bd ready --json

Filtering

bd ready --type bug --json

Molecule Mode

bd ready --mol bd-mol-abc --json

Sorting

bd ready --sort priority --json

Cross-Rig

bd ready --rig gastown --json

Metadata Filtering

bd ready --metadata-field team=platform --json

JSON Output

With --json flag:

[
  {
    "issue": {
      "id": "bd-123",
      "title": "Fix login bug",
      "status": "open",
      "priority": 1,
      "issue_type": "bug",
      "labels": ["backend", "security"],
      "dependencies": []
    },
    "dependency_count": 0,
    "dependent_count": 3,
    "comment_count": 2,
    "parent": null
  }
]

Molecule Ready Output

With --mol flag and --json:

{
  "molecule_id": "bd-mol-abc",
  "molecule_title": "Deploy v2.0",
  "total_steps": 5,
  "ready_steps": 2,
  "steps": [
    {
      "issue": {
        "id": "bd-abc.1",
        "title": "Run tests",
        "status": "open",
        "priority": 1
      },
      "parallel_info": {
        "is_ready": true,
        "can_parallel": ["bd-abc.2"]
      },
      "parallel_group": "test-suite"
    }
  ],
  "parallel_groups": {
    "test-suite": ["bd-abc.1", "bd-abc.2"]
  }
}

Display Modes

Pretty Format (Default)

Tree-style display with visual indicators:

📋 Ready work (3 issues with no active blockers):

● P1 [bug] bd-123: Fix login bug
  Epic: User authentication
  
○ P2 [task] bd-124: Add logging
  
● P1 [feature] bd-125: Dark mode
  Estimate: 180 min

Plain Format

Numbered list for scripting:

1. [P1] [bug] bd-123: Fix login bug
   Estimate: 60 min
   Assignee: unassigned

2. [P2] [task] bd-124: Add logging

Blocker Semantics

An issue is “ready” if:

Status is open (not in_progress, blocked, deferred, hooked, closed)
No open blocking dependencies (all blocks deps are closed)
Parent is closed (for parent-child relationships)
Not deferred (unless --include-deferred)
Not ephemeral (unless --include-ephemeral)

Issues with status=blocked are excluded even if blockers are closed. Use bd update to change status to open.

Best Practices

For Agents

Start with bd ready --json to find work
Use --unassigned to avoid conflicts
Filter by --label for area expertise
Claim immediately with bd update --claim

For Humans

Use --pretty for visual scanning
Filter by --priority for urgent work
Check --parent for epic-specific tasks
Review estimate before claiming

Agent Workflow

# 1. Find ready work
issue_id=$(bd ready --unassigned --json | jq -r '.[0].issue.id')

# 2. Claim it atomically
bd update $issue_id --claim --json

# 3. Work on it
# ...

# 4. Close when done
bd close $issue_id --reason "Completed" --json

Comparison: ready vs list —ready

Feature	`bd ready`	`bd list --ready`
Blocker check	✅ Yes	❌ No
Parent check	✅ Yes	❌ No
Deferred check	✅ Yes	❌ No
Status filter	`open` only	`open` only
Performance	Optimized	Slower

Always use bd ready for finding work, not bd list --ready.

bd blocked - Show blocked issues and blockers
bd update --claim - Claim ready work
bd list - General issue search
bd dep tree - Visualize blocking relationships

Commands

Advanced Commands

Memory Commands

Molecule Commands

Usage

Description

Parameters

Filtering

Molecule Mode

Sorting

Display

Advanced

Output

Examples

Basic Usage

Filtering

Molecule Mode

Sorting

Cross-Rig

Metadata Filtering

JSON Output

Molecule Ready Output

Display Modes

Pretty Format (Default)

Plain Format

Blocker Semantics

Best Practices

For Agents

For Humans

Agent Workflow

Comparison: ready vs list —ready

Build docs developers (and LLMs) love

Commands

Advanced Commands

Memory Commands

Molecule Commands

​Usage

​Description

​Parameters

​Filtering

​Molecule Mode

​Sorting

​Display

​Advanced

​Output

​Examples

​Basic Usage

​Filtering

​Molecule Mode

​Sorting

​Cross-Rig

​Metadata Filtering

​JSON Output

​Molecule Ready Output

​Display Modes

​Pretty Format (Default)

​Plain Format

​Blocker Semantics

​Best Practices

​For Agents

​For Humans

​Agent Workflow

​Comparison: ready vs list —ready

​Related Commands

Build docs developers (and LLMs) love

Usage

Description

Parameters

Filtering

Molecule Mode

Sorting

Display

Advanced

Output

Examples

Basic Usage

Filtering

Molecule Mode

Sorting

Cross-Rig

Metadata Filtering

JSON Output

Molecule Ready Output

Display Modes

Pretty Format (Default)

Plain Format

Blocker Semantics

Best Practices

For Agents

For Humans

Agent Workflow

Comparison: ready vs list —ready

Related Commands