Getting Started

Install tx and run your first agent loop

Get up and running with tx in minutes. tx provides four interfaces -- pick whichever fits your workflow.

Interface	Package	Best For
CLI	`@jamesaphoenix/tx-cli`	Shell scripts, human operators
TypeScript SDK	`@jamesaphoenix/tx-agent-sdk`	Custom agents in Node/Bun
MCP Server	`@jamesaphoenix/tx-mcp-server`	Claude, Cursor, AI IDEs
REST API	`@jamesaphoenix/tx-api-server`	Language-agnostic HTTP clients

Installation

Install the CLI globally:

npm install -g @jamesaphoenix/tx-cli

Or with your preferred package manager:

# pnpm
pnpm add -g @jamesaphoenix/tx-cli

# bun
bun add -g @jamesaphoenix/tx-cli

Add the Agent SDK to your project:

npm install @jamesaphoenix/tx-agent-sdk

The SDK supports two modes:

HTTP mode -- connects to the API server (recommended for distributed agents)
Direct mode -- reads SQLite directly (for local, single-process agents)

Add the MCP server to your Claude Desktop or IDE configuration:

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

No separate API server is needed -- the MCP server accesses the SQLite database directly.

Launch the API server:

npx @jamesaphoenix/tx-api-server

Or with bun:

bunx @jamesaphoenix/tx-api-server

The server runs on http://localhost:3456 by default. Configure with flags or environment variables:

# Custom port
npx @jamesaphoenix/tx-api-server --port 8080

# Custom database path
npx @jamesaphoenix/tx-api-server --db /path/to/tasks.db

# Environment variables
TX_API_PORT=8080 TX_DB_PATH=./my.db npx @jamesaphoenix/tx-api-server

Initialize Your Project

Navigate to your project directory and initialize tx:

cd your-project
tx init

This creates a .tx/ directory:

.tx/
├── tasks.db           # SQLite database (gitignored)
├── tasks.jsonl        # Git-tracked task history
├── learnings.jsonl    # Git-tracked learnings
└── runs.jsonl         # Git-tracked run history

Quick Start

# Create a task
tx add "Implement user authentication"

# See what's ready to work on
tx ready

# Complete a task (unblocks dependents automatically)
tx done tx-abc123

# Add a dependency: tx-b waits for tx-a
tx block tx-b tx-a

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

// HTTP mode (requires API server running)
const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Or direct SQLite mode (no server needed)
// const tx = new TxClient({ dbPath: '.tx/tasks.db' })

// Create a task
const task = await tx.tasks.create({ title: 'Implement auth' })

// Get ready tasks
const ready = await tx.tasks.ready({ limit: 5 })

// Complete a task
await tx.tasks.done(ready[0].id)

Once configured, your AI assistant has access to these tools:

Tool	Description
`tx_add`	Create a task
`tx_ready`	List unblocked tasks
`tx_done`	Complete a task
`tx_block`	Add a dependency
`tx_show`	View task details
`tx_context`	Get relevant learnings

Example prompt: "Use tx_ready to find the highest priority task, then work on it and mark it done with tx_done."

# Create a task
curl -X POST http://localhost:3456/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Implement auth"}'

# List ready tasks
curl http://localhost:3456/tasks/ready?limit=5

# Complete a task
curl -X POST http://localhost:3456/tasks/tx-abc123/done

Launching the API Server

The Agent SDK (HTTP mode) and REST API interface require the API server to be running. The CLI and MCP server access SQLite directly and do not need it.

# Start the API server
npx @jamesaphoenix/tx-api-server

# Or with bun
bunx @jamesaphoenix/tx-api-server

The server binds to http://localhost:3456 by default. Available options:

Flag	Env Variable	Default	Description
`--port`, `-p`	`TX_API_PORT`	`3456`	Port to listen on
`--host`	`TX_API_HOST`	`127.0.0.1`	Hostname to bind to
`--db`	`TX_DB_PATH`	`.tx/tasks.db`	Path to SQLite database
--	`TX_API_KEY`	--	API key for authentication (optional)

Your First Agent Loop

The simplest agent loop pulls tasks one at a time:

#!/bin/bash
while true; do
  # Get highest priority ready task
  TASK=$(tx ready --json --limit 1 | jq -r '.[0].id // empty')

  # Exit if no ready tasks
  [ -z "$TASK" ] && break

  # Let Claude work on it
  claude "Your task is $TASK. Run 'tx show $TASK' for details. When done, run 'tx done $TASK'"
done

echo "All tasks complete!"

Store and Retrieve Learnings

As you work, capture knowledge that should persist:

# Store a learning
tx learning:add "Use bcrypt for password hashing, not SHA256"
tx learning:add "The auth service requires Redis for session storage"

# Search learnings
tx learning:search "authentication"

# Get context for a specific task (relevant learnings auto-selected)
tx context tx-abc123

Sync with Git

tx stores data in SQLite for speed, but syncs to JSONL for git:

# Export to git-trackable files
tx sync export

# Import from JSONL (e.g., after git pull)
tx sync import

Add to your workflow:

# Before committing
tx sync export && git add .tx/*.jsonl

# After pulling
git pull && tx sync import

Example Orchestration Patterns

Parallel Agents

Run multiple agents pulling from the same queue:

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

Human-in-Loop

Agent proposes, human approves:

task=$(tx ready --json --limit 1 | jq -r '.[0].id')
claude "Plan implementation for $task" > plan.md
echo "Review plan.md, then press Enter to continue..."
read
claude "Execute plan.md"
tx done $task

Project Structure

your-project/
├── .tx/
│   ├── tasks.db           # SQLite (gitignored)
│   ├── tasks.jsonl        # Tasks (git-tracked)
│   ├── learnings.jsonl    # Learnings (git-tracked)
│   └── runs.jsonl         # Run history (git-tracked)
├── CLAUDE.md              # Agent instructions (optional)
└── ...your code

Next Steps

CLI Primitives -- Full reference for all tx commands
tx ready -- Deep dive into task readiness detection
tx context -- Contextual learning retrieval
tx sync -- Git synchronization details

Quick Reference

# Tasks
tx add <title>              # Create task
tx ready                    # List unblocked tasks
tx done <id>                # Complete task
tx block <id> <blocker>     # Add dependency
tx tree <id>                # Show hierarchy
tx show <id>                # View task details

# Memory
tx learning:add <content>   # Store learning
tx learning:search <query>  # Find learnings
tx context <task-id>        # Get relevant context

# Sync
tx sync export              # SQLite → JSONL
tx sync import              # JSONL → SQLite

# API Server
npx @jamesaphoenix/tx-api-server   # Start REST API

Getting Started

On this page