tx

tx auto 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. That lets you work on discovery tasks without seeing implementation tasks.

Usage

tx auto label add <name> [--color <hex>]
tx auto label assign <task-id> <label>
tx auto label unassign <task-id> <label>
tx auto label list
# Create labels for phases
tx auto label add "phase:discovery"
tx auto label add "phase:implement"
tx auto label add "sprint:w10"

# Assign labels to tasks
tx auto label assign tx-abc123 "phase:discovery"
tx auto 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 auto 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.

tx_auto_label_add

Create a new label.

{
  "name": "tx_auto_label_add",
  "arguments": {
    "name": "phase:discovery",
    "color": "#3b82f6"
  }
}
ArgTypeRequiredDescription
namestringYesLabel name (e.g. 'phase:discovery')
colorstringNoHex color code (e.g. '#3b82f6')

tx_auto_label_delete

Delete a label.

{
  "name": "tx_auto_label_delete",
  "arguments": {
    "name": "phase:discovery"
  }
}
ArgTypeRequiredDescription
namestringYesLabel name to delete

tx_auto_label_assign

Assign a label to a task.

{
  "name": "tx_auto_label_assign",
  "arguments": {
    "taskId": "tx-abc123",
    "labelName": "phase:discovery"
  }
}
ArgTypeRequiredDescription
taskIdstringYesTask ID to assign the label to
labelNamestringYesLabel name to assign

tx_auto_label_unassign

Remove a label from a task.

{
  "name": "tx_auto_label_unassign",
  "arguments": {
    "taskId": "tx-abc123",
    "labelName": "phase:discovery"
  }
}
ArgTypeRequiredDescription
taskIdstringYesTask ID to remove the label from
labelNamestringYesLabel name to remove

tx_auto_label_list

List all labels. No arguments required.

{
  "name": "tx_auto_label_list",
  "arguments": {}
}

Label filtering on tx_ready and tx_list

Label filtering is also supported on tx_ready and tx_list:

{
  "name": "tx_ready",
  "arguments": {
    "labels": "phase:discovery",
    "excludeLabels": "needs-review",
    "limit": 5
  }
}
ArgTypeRequiredDescription
limitnumberNoMaximum tasks to return
labelsstringNoComma-separated label names to include (e.g. 'phase:implement,sprint:w10')
excludeLabelsstringNoComma-separated label names to exclude (e.g. 'needs-review')
# 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 auto 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 auto verify run $task && tx done $task"
done

tx memory

Headless search over markdown directories: index, search, tag, and navigate your knowledge graph

tx auto guard

Set task creation limits to prevent unbounded proliferation

On this page

PurposeUsagetx_auto_label_addtx_auto_label_deletetx_auto_label_assigntx_auto_label_unassigntx_auto_label_listLabel filtering on tx_ready and tx_listPhase WorkflowRelated Commands