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

> List ready tasks in Beads with the bd ready command or store.GetReadyWork() Go API. Discover issues without active blockers for immediate development.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/internal/storage/embeddeddolt/queries.go), which implements the `GetReadyWork` method, while [`internal/storage/issueops/ready_work.go`](https://github.com/gastownhall/beads/blob/main/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.

```bash

# 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`](https://github.com/gastownhall/beads/blob/main/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:

```bash
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`](https://github.com/gastownhall/beads/blob/main/internal/types/types.go) and executed by the storage layer.

```go
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`](https://github.com/gastownhall/beads/blob/main/internal/storage/embeddeddolt/queries.go).
- The `WorkFilter` struct (see [`types.go`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.

```bash

# 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`](https://github.com/gastownhall/beads/blob/main/internal/types/types.go).
- **Understand the data flow**: The CLI in [`cmd/bd/ready.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/ready.go) calls the storage layer in [`internal/storage/embeddeddolt/queries.go`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/ready.go)) uses a dedicated formatter optimized for the ready queue workflow, while `bd list --ready` (from [`cmd/bd/list.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/list.go)) applies the standard list view formatting and column selection to ready-filtered results.