tx ready

List tasks that are ready to work on

Purpose

tx ready returns tasks that are ready to be worked on. A task is ready when:

Its status is workable (backlog, ready, planning, active, blocked, or review)
All tasks blocking it have status done

Tasks are sorted by score (highest first), making it easy for agents to pick the highest-priority unblocked task.

Usage

tx ready [options]

# Top 10 ready tasks
tx ready

# Top 5 ready tasks
tx ready -n 5

# JSON output for scripting
tx ready --json

# Get the ID of the highest-priority ready task
tx ready --json --limit 1 | jq -r '.[0].id'

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

// HTTP mode
const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Or direct SQLite mode
const tx = new TxClient({ dbPath: '.tx/tasks.db' })

// Get ready tasks
const ready = await tx.tasks.ready({ limit: 5 })
// Returns SerializedTaskWithDeps[] with:
//   id, title, status, score, blockedBy, blocks, children, isReady,
//   groupContext, effectiveGroupContext, effectiveGroupContextSourceTaskId

Tool name: tx_ready

Arguments:

Arg	Type	Required	Description
`limit`	`number`	No	Maximum tasks to return (default: 10)

Example request:

{
  "name": "tx_ready",
  "arguments": {
    "limit": 5
  }
}

GET /api/tasks/ready?limit=5

Query parameters:

Param	Type	Required	Description
`limit`	`number`	No	Maximum tasks to return (default: 10)

Example:

curl http://localhost:3456/api/tasks/ready?limit=5

Options

Option	Description
`--limit, -n <n>`	Maximum tasks to show (default: 10)
`--claim <worker-id>`	Atomically claim the first ready task for the given worker
`--lease <minutes>`	Lease duration when using `--claim` (default: 30)
`--json`	Output as JSON for scripting
`--help`	Show help

Output

Text Output

Ready tasks (sorted by score):

 1. tx-abc123  [800]  Implement authentication
 2. tx-def456  [600]  Add login page
 3. tx-ghi789  [500]  Write unit tests

JSON Output

[
  {
    "id": "tx-abc123",
    "title": "Implement authentication",
    "status": "ready",
    "score": 800,
    "blockedBy": [],
    "blocks": ["tx-def456"],
    "children": [],
    "isReady": true,
    "groupContext": null,
    "effectiveGroupContext": "Shared auth rollout context",
    "effectiveGroupContextSourceTaskId": "tx-root001"
  }
]

TaskWithDeps Response

Every response includes full dependency information per Rule 1:

Field	Type	Description
`blockedBy`	`TaskId[]`	Task IDs that block this task
`blocks`	`TaskId[]`	Task IDs this task blocks
`children`	`TaskId[]`	Direct child task IDs
`isReady`	`boolean`	Whether this task can be worked on
`groupContext`	`string \| null`	Direct task-group context set on this task
`effectiveGroupContext`	`string \| null`	Inherited task-group context used for this task
`effectiveGroupContextSourceTaskId`	`TaskId \| null`	Task ID that provided `effectiveGroupContext`

Task-Group Context Inheritance

tx ready includes inherited task-group context fields so agents can pick up shared context automatically.

Set or clear direct context through the interface you are already using:

tx group-context set tx-root001 "Shared auth rollout context"
tx group-context clear tx-root001

await tx.tasks.setGroupContext("tx-root001", "Shared auth rollout context")
await tx.tasks.clearGroupContext("tx-root001")

{ "name": "tx_group_context_set", "arguments": { "taskId": "tx-root001", "context": "Shared auth rollout context" } }
{ "name": "tx_group_context_clear", "arguments": { "taskId": "tx-root001" } }

curl -X PUT http://localhost:3456/api/tasks/tx-root001/group-context \
  -H "Content-Type: application/json" \
  -d '{"context":"Shared auth rollout context"}'

curl -X DELETE http://localhost:3456/api/tasks/tx-root001/group-context

When running multiple workers in parallel, use --claim to atomically fetch the highest-priority ready task and claim it in a single operation. This eliminates the race window between tx ready and tx claim where multiple workers could pick the same task.

# Atomically get and claim the top ready task
tx ready --json --limit 1 --claim worker-1 --lease 30

# Returns the claimed task with claim info, or empty if nothing available

The --claim flag:

Fetches a small batch of ready candidates (sorted by score)
Attempts to claim each one in priority order
Returns the first successfully claimed task
Returns null if no tasks could be claimed (all taken by other workers)

This is the recommended approach for parallel agent loops. See tx claim for more on the claim lifecycle.

Agent Loop Pattern

#!/bin/bash
# Simple agent loop using tx ready

while true; do
  # Get highest priority ready task
  TASK=$(tx ready --json --limit 1 | jq -r '.[0].id // empty')

  # Exit if no ready tasks
  [ -z "$TASK" ] && break

  # Work on the task
  claude "Your task is $TASK. Run 'tx show $TASK' to see details."

  # Mark complete
  tx done "$TASK"
done

echo "All tasks complete!"

Parallel Agent Loop (Recommended)

#!/bin/bash
# Parallel agent loop using atomic ready+claim
WORKER_ID="worker-$$"

while true; do
  RESULT=$(tx ready --json --limit 1 --claim "$WORKER_ID" --lease 30)
  TASK=$(echo "$RESULT" | jq -r '.task.id // empty')
  [ -z "$TASK" ] && break

  claude "Your task is $TASK. Run 'tx show $TASK' for details."
  tx done "$TASK"
done

tx done - Mark a task as complete
tx dep block - Add dependencies between tasks
tx memory context - Get memory relevant to a task