tx label

Organize tasks with labels for ready queue scoping

Purpose

Labels let you organize tasks into phases, sprints, or categories. Use them with tx ready --label to scope the ready queue — work on discovery tasks without seeing implementation tasks.

Usage

tx label add <name> [--color <hex>]
tx label assign <task-id> <label>
tx label unassign <task-id> <label>
tx label list

# Create labels for phases
tx label add "phase:discovery"
tx label add "phase:implement"
tx label add "sprint:w10"

# Assign labels to tasks
tx label assign tx-abc123 "phase:discovery"
tx label assign tx-def456 "phase:implement"

# Scope the ready queue
tx ready --label "phase:discovery"

# Exclude labels
tx ready --exclude-label "needs-review"

# List all labels
tx label list

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

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

// Scope ready queue by label
const discovery = await tx.tasks.ready({
  labels: ['phase:discovery'],
  limit: 5,
})

// Exclude labels
const tasks = await tx.tasks.ready({
  excludeLabels: ['needs-review'],
})

The SDK supports label-based filtering on ready() and list(). Label CRUD (add, assign, unassign) is currently available via the CLI only.

Label filtering is supported on tx_ready and tx_list:

{
  "name": "tx_ready",
  "arguments": {
    "labels": "phase:discovery",
    "excludeLabels": "needs-review",
    "limit": 5
  }
}

Arg	Type	Required	Description
`limit`	`number`	No	Maximum tasks to return
`labels`	`string`	No	Comma-separated label names to include (e.g. `'phase:implement,sprint:w10'`)
`excludeLabels`	`string`	No	Comma-separated label names to exclude (e.g. `'needs-review'`)

Label CRUD (add, assign, unassign) is currently available via the CLI only.

# Get ready tasks filtered by label
curl "http://localhost:3456/api/tasks/ready?labels=phase:discovery&limit=5"

# Exclude labels from ready queue
curl "http://localhost:3456/api/tasks/ready?excludeLabels=needs-review"

# List tasks filtered by label
curl "http://localhost:3456/api/tasks?labels=phase:implement"

Label filtering is supported on the ready and list endpoints. Label CRUD (add, assign, unassign) is currently available via the CLI only.

Phase Workflow

#!/bin/bash
# Phase 1: Discovery
tx guard set --max-pending 20

while task=$(tx ready --label "phase:discovery" --json --limit 1 | jq -r '.[0].id // empty'); do
  [ -z "$task" ] && break
  claude "Investigate $task. When done: tx done $task"
done

# Phase 2: Implementation
while task=$(tx ready --label "phase:implement" --json --limit 1 | jq -r '.[0].id // empty'); do
  [ -z "$task" ] && break
  claude "Implement $task. Verify with: tx verify run $task && tx done $task"
done

tx ready — Get next workable task (with label filtering)
tx guard — Set task creation limits per phase
tx verify — Attach machine-checkable done criteria
tx reflect — Analyze session metrics

tx label

Purpose

Usage

Phase Workflow

Related Commands

On this page