tx done

Mark a task as complete

Purpose

tx done marks a task as complete by setting its status to done. This is the primary way to signal that work on a task is finished.

When a task is completed, any tasks that were waiting on it may become unblocked. The command reports which tasks are newly unblocked.

Usage

tx done <id> [--human] [options]

# Mark a task as complete
tx done tx-abc123

# Mark a task as complete as a human caller
tx done tx-abc123 --human

# Complete a task and get JSON response
tx done tx-abc123 --json

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

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

const { task, nowReady } = await tx.tasks.done('tx-abc123')
// task: SerializedTaskWithDeps (the completed task)
// nowReady: SerializedTaskWithDeps[] (tasks that became ready after completion)

{
  "name": "tx_done",
  "arguments": {
    "id": "tx-abc123"
  }
}

POST /api/tasks/:id/done

# Agent caller (default if header is omitted)
curl -X POST http://localhost:3456/api/tasks/tx-abc123/done \
  -H "x-tx-actor: agent"

# Human-operated REST client
curl -X POST http://localhost:3456/api/tasks/tx-abc123/done \
  -H "x-tx-actor: human"

Arguments

Options

Actor Semantics

Task completion is actor-aware.

• CLI defaults to agent. Pass --human when a person is completing the task from the terminal.
• REST API completion requests default to agent. Direct human-operated clients must send x-tx-actor: human.
• The dashboard already sends x-tx-actor: human for task update and completion requests.
• The TypeScript SDK HTTP client sends x-tx-actor: agent.

This matters when completion rules depend on whether the caller is an agent or a human.

Gate-Linked Tasks

A pin is a named persistent record that tx stores in the database and can sync into agent context files. Gates are implemented as special pins with IDs like gate.docs-to-build, whose JSON state can optionally include a linked taskId.

When that gate pin stores a task ID and .tx/config.toml keeps the default:

[pins]
block_agent_done_when_task_id_present = true

agent-driven completion of that linked task is blocked.

Use one of these human paths to finish the task:

• CLI: tx done <id> --human
• REST API: POST /api/tasks/:id/done with x-tx-actor: human
• Dashboard: no extra work; the dashboard already sends the human actor header

See tx pin for the underlying storage primitive and tx gate for the full human review pattern.

Output

Text Output

Task tx-abc123 marked as done.

Newly unblocked tasks:
  tx-def456  Add login page
  tx-ghi789  Write integration tests

JSON Output

{
  "task": {
    "id": "tx-abc123",
    "title": "Implement authentication",
    "status": "done",
    "score": 800,
    "blockedBy": [],
    "blocks": ["tx-def456", "tx-ghi789"],
    "children": [],
    "isReady": false
  },
  "unblocked": ["tx-def456", "tx-ghi789"]
}

Cascade Unblocking

When you complete a task, tx automatically checks which tasks were waiting on it:

Before tx done tx-auth:

  tx-auth [done]
      | blocks
  tx-login [blocked]
      | blocks
  tx-dashboard [blocked]

After tx done tx-auth:

  tx-auth [done]
      | blocks
  tx-login [ready]     <-- Newly unblocked!
      | blocks
  tx-dashboard [blocked]  <-- Still blocked by tx-login

Agent Workflow

#!/bin/bash
# Complete a task and immediately start the next one

# Finish current task
tx done tx-abc123

# Get next ready task
NEXT=$(tx ready --json --limit 1 | jq -r '.[0].id // empty')

if [ -n "$NEXT" ]; then
  echo "Next task: $NEXT"
  tx show "$NEXT"
fi

Idempotency

Calling tx done on an already-completed task is a no-op. The task remains in done status and no error is raised.

tx done tx-abc123  # First call: marks as done
tx done tx-abc123  # Second call: no-op, already done

Related Commands

• tx ready - List tasks that are ready to work on
• tx block - Add dependencies between tasks
• tx reset - Reset a task back to ready status