Primitives

Composable building blocks for agent infrastructure

Overview

tx provides a set of composable primitives for managing tasks, dependencies, memory, and stream-log synchronization. These primitives are the building blocks for any agent orchestration pattern.

If you are new to tx, do not try to learn everything at once. Use this order:

1. Task Management
2. Spec-Driven Development
3. Memory & Context
4. Bounded Autonomy
5. Coordination
6. Observability

Philosophy

tx is about primitives, not frameworks. We don't dictate how you orchestrate your agents. Instead, we provide headless infrastructure that you compose however you need.

Access Patterns

Every tx primitive is available through multiple interfaces. Choose the one that fits your workflow:

curl -fsSL https://raw.githubusercontent.com/jamesaphoenix/tx/main/install.sh | sh
tx ready --limit 5

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

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })
// or: new TxClient({ dbPath: '.tx/tasks.db' })

const ready = await tx.tasks.ready({ limit: 5 })
const { task, nowReady } = await tx.tasks.done(ready[0].id)
await tx.memory.add({ title: 'Use retry logic for flaky calls', tags: ['learning'] })

{
  "mcpServers": {
    "tx": {
      "command": "npx",
      "args": ["@jamesaphoenix/tx-mcp-server"]
    }
  }
}

npx @jamesaphoenix/tx-api-server
# Server running on http://localhost:3456

curl http://localhost:3456/api/tasks/ready?limit=5
curl -X POST http://localhost:3456/api/tasks/tx-abc123/done

Update And Completion Actor Semantics

Task update and completion flows can behave differently for agents and humans.

• REST API task update and completion requests default to agent. If a human is driving the request from curl, a script, or a custom UI, send x-tx-actor: human.
• The dashboard already sends x-tx-actor: human for task update and completion requests.
• CLI task updates and completion default to agent. Use --human on commands such as tx done and tx update when a person is performing the action.
• This is most visible with gate-linked tasks. If a gate pin stores taskId and .tx/config.toml leaves [pins].block_agent_done_when_task_id_present = true (default), agent callers cannot complete that linked task.

See tx done and tx gate for the concrete completion rules.

Recommended Learning Order

0. Agent Setup And Workflow Surfaces

1. Task Management

Start here if you are evaluating tx. This is the smallest loop that proves queueing, dependencies, and persistence.

2. Spec-Driven Development

Add this once the task loop feels natural and you want intent, decomposition, tests, and closure to stay aligned.

3. Memory & Context

Bring this in once you want durable context, reusable learnings, and automatic prompt enrichment.

4. Bounded Autonomy

Use these when agents start doing enough work that you need boundaries, checks, and human checkpoints.

5. Coordination

Reach for coordination once more than one worker, operator, or long-lived channel is involved.

6. Observability

Use observability after the earlier layers are in place and you need to understand what is drifting, failing, or stuck.

Quick CLI Examples

tx pin set coding-standards --file ./standards.md
tx memory search "database schema" --semantic
tx memory add "Use WAL mode for SQLite" -t learning
tx memory context tx-abc123
tx auto verify set tx-abc123 "bun test"
tx auto verify run tx-abc123

Example Orchestration Patterns

We ship example patterns, not a required workflow:

Simple: One Agent, One Task

while task=$(tx ready --limit 1 --json | jq -r '.[0].id'); do
  claude "Work on task $task, then run: tx done $task"
done

Parallel: N Agents Pulling from Queue

for i in {1..5}; do
  (while task=$(tx ready --limit 1 --json | jq -r '.[0].id'); do
    claude "Complete $task" && tx done $task
  done) &
done
wait

Human-in-Loop: Agent Proposes, Human Approves

task=$(tx ready --limit 1 --json | jq -r '.[0].id')
claude "Read the project instructions (for example AGENTS.md if present). For task $task: run tx show $task, make sure a paired PRD/design doc is linked, then decompose the work into tx subtasks and dependency edges."
echo "Review tx show $task, tx dep tree $task, and the linked PRD/DD docs, then press Enter to continue..."
read
claude "Read the project instructions (for example AGENTS.md if present). For task $task: execute the approved ready work from the linked PRD/DD docs and keep tx updated."

Global Options

All primitives support these global options:

Task Lifecycle

backlog → ready → planning → active → blocked → review → needs_review → done

A task is ready when:

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