How to List Tasks That Are Ready to Be Worked on in Beads

Use the bd ready command to display only issues that have no active blockers and are ready for development, or call store.GetReadyWork() from the Go API for programmatic access.

Beads is a dependency-aware issue tracker that automatically computes which tasks can begin immediately. According to the gastownhall/beads source code, the ready queue filters out blocked, deferred, and ephemeral issues so teams always see actionable work. You can access this queue via the CLI or integrate it directly into your Go applications.

Understanding the Ready Queue Logic

The ready queue operates by computing dependency graphs to identify truly unblocked work. As implemented in cmd/bd/ready.go, the system executes three core steps:

1. Fetches all open issues from the embedded Dolt store.
2. Computes blocked IDs using relationship types including blocks, waits-for, and parent/child hierarchies.
3. Filters out any issue appearing in the blocked set, deferred issues with future dates, and ephemerals unless explicitly requested.

The core logic resides in internal/storage/embeddeddolt/queries.go, which implements the GetReadyWork method, while internal/storage/issueops/ready_work.go wraps this query in a transaction and applies the WorkFilter.

Using the CLI to List Ready Tasks

The fastest way to see ready work is the bd ready command. This outputs a human-readable table of issues that can be started immediately.

# Display ready issues in a formatted table

bd ready

# Export as JSON for scripts or dashboards

bd ready --json

# Show only the top 3 highest-priority items

bd ready --priority 1 --limit 3

Available Filter Flags

The bd ready command supports several flags defined in cmd/bd/ready.go to narrow results:

• --priority – Filter by priority level (e.g., 1 for P1).
• --limit – Cap the number of returned rows.
• --exclude-label – Remove issues with specific labels (e.g., triage:pending).

For example, to show ready work but hide items awaiting review:

bd ready --json | jq '[.[] | select(.labels | index("needs-review") | not)]'

Programmatic Access with the Go API

For custom tooling, import the github.com/gastownhall/beads package and call GetReadyWork with a WorkFilter struct. This pattern is defined in internal/types/types.go and executed by the storage layer.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/gastownhall/beads"
	"github.com/gastownhall/beads/internal/types"
)

func main() {
	ctx := context.Background()

	// Open the default Beads store (embedded Dolt)
	store, err := beads.OpenStore()
	if err != nil {
		log.Fatalf("open store: %v", err)
	}
	defer store.Close()

	// Build a filter for ready, open issues with priority ≤ P1
	filter := types.WorkFilter{
		Status:   types.StatusOpen,
		Priority: func() *int { p := 1; return &p }(),
		Limit:    10,
	}

	readyIssues, err := store.GetReadyWork(ctx, filter)
	if err != nil {
		log.Fatalf("GetReadyWork: %v", err)
	}

	fmt.Printf("Found %d ready issues:\n", len(readyIssues))
	for _, i := range readyIssues {
		fmt.Printf("- %s (priority %d, type %s)\n", i.ID, *i.Priority, i.Type)
	}
}

Key implementation details:

• store.GetReadyWork delegates to EmbeddedDoltStore.GetReadyWork in internal/storage/embeddeddolt/queries.go.
• The WorkFilter struct (see types.go) supports filtering by status, priority, type, parent, and other fields.

Alternative: Using bd list --ready

The bd list command also provides access to the ready queue. According to cmd/bd/list.go, invoking bd list --ready reuses the same underlying GetReadyWork function but presents the data in the standard list format rather than the dedicated ready view.

# Alternative syntax that also shows ready work

bd list --ready --limit 5

Summary

• Run bd ready to see a human-readable list of unblocked issues, or use --json for machine parsing.
• Filter results using flags like --priority, --limit, and --exclude-label to focus on specific workstreams.
• Access programmatically via store.GetReadyWork(ctx, filter) from the Go library, using the WorkFilter struct defined in internal/types/types.go.
• Understand the data flow: The CLI in cmd/bd/ready.go calls the storage layer in internal/storage/embeddeddolt/queries.go, which computes blocked IDs via the dependency graph before returning results.

Frequently Asked Questions

What does "ready" mean in Beads?

A task is considered ready when it has no active blockers in the dependency graph, is not deferred to a future date, and is not an ephemeral issue. The system computes this by analyzing blocks, waits-for, and parent/child relationships, then filtering out any ID that appears in the blocked set.

How do I exclude specific labels from the ready list?

Use the --exclude-label flag when running bd ready. For example, bd ready --exclude-label triage:pending hides all ready items that carry the "triage:pending" label, letting you focus on validated work.

Can I use bd ready in shell scripts?

Yes. Append the --json flag to produce machine-readable JSON output that pipes cleanly into tools like jq or python. For example: bd ready --json | jq '.[] | select(.priority == 1)' extracts only P1 ready items.

What is the difference between bd ready and bd list --ready?

Both commands return the same underlying data set computed by GetReadyWork, but bd ready (defined in cmd/bd/ready.go) uses a dedicated formatter optimized for the ready queue workflow, while bd list --ready (from cmd/bd/list.go) applies the standard list view formatting and column selection to ready-filtered results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}