tx

Primitives

Composable building blocks for agent infrastructure

Overview

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

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.

┌─────────────────────────────────────────────────────┐
│  Your Orchestration (your code, your rules)         │
├─────────────────────────────────────────────────────┤
│  tx primitives                                      │
│                                                     │
│   tx ready     tx done      tx context    tx learn  │
│   tx claim     tx block     tx sync       tx trace  │
│                                                     │
└─────────────────────────────────────────────────────┘

Access Patterns

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

Install globally and use from any terminal or shell script:

npm install -g @jamesaphoenix/tx
tx ready --limit 5

Best for: shell scripts, agent loops, CI/CD pipelines.

Use the SDK for programmatic access with full type safety:

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.learnings.add({ content: 'Use retry logic for flaky calls' })

Best for: TypeScript/JavaScript agents, custom orchestrators, programmatic workflows.

Use tx as an MCP server for Claude, Cursor, or any MCP-compatible client:

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

Tools: tx_ready, tx_done, tx_block, tx_add, tx_context, tx_learning_add, etc.

Best for: AI assistants, Claude Code, Cursor, IDE integrations.

Run the API server for HTTP access from any language:

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

Best for: non-TypeScript agents, distributed systems, web dashboards.

Core Primitives

PrimitivePurposeInterfacesStatus
tx readyGet next workable task (unblocked, highest priority)CLI, SDK, MCP, APIAvailable
tx doneComplete task, potentially unblocking othersCLI, SDK, MCP, APIAvailable
tx blockDeclare dependencies between tasksCLI, SDK, MCP, APIAvailable
tx claimClaim task with lease to prevent parallel collisionsCLI, SDK, MCP, APIAvailable
tx contextGet relevant learnings for prompt injectionCLI, SDK, MCP, APIAvailable
tx learning:*Record and search knowledgeCLI, SDK, MCP, APIAvailable
tx syncPersist to git-friendly JSONLCLI, SDKAvailable
tx try / tx attemptsRecord and track implementation attemptsCLI, SDK, MCP, APIAvailable
tx doc *Docs-as-primitives with YAML structured documentationCLI, SDK, MCP, APIAvailable
tx invariant *Machine-checkable system rules with enforcement trackingCLI, SDK, MCP, APIAvailable
tx trace *Execution tracing and run observabilityCLI, SDK, MCP, APIAvailable

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 "Plan implementation for $task" > plan.md
read -p "Approve? [y/n] " && claude "Execute plan.md"
tx done $task

Global Options

All primitives support these global options:

OptionDescription
--jsonOutput as JSON for scripting
--db <path>Custom database path (default: .tx/tasks.db)
--helpShow command help

Task Lifecycle

backlog → ready → planning → active → blocked → review → human_needs_to_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

On this page

OverviewPhilosophyAccess PatternsCore PrimitivesExample Orchestration PatternsSimple: One Agent, One TaskParallel: N Agents Pulling from QueueHuman-in-Loop: Agent Proposes, Human ApprovesGlobal OptionsTask Lifecycle