Getting Started

Install tx, finish your first task loop, then add docs-first specs

Get up and running with tx in minutes. The recommended path is simple:

Start with the CLI and finish one task loop.
Add docs-first spec tracing once the task loop feels natural.
Layer on MCP, SDK, API, and the heavier controls only when you need them.

tx provides four interfaces. You can add the others after the CLI path is working.

Interface	Package	Best For
CLI	`@jamesaphoenix/tx-cli`	Shell scripts, agent loops
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

At A Glance

Interface Paths

Rendering diagram…

CLI, MCP, and SDK direct mode use SQLite directly. REST and SDK HTTP mode go through the API server, which also reads the same SQLite store.

Work Loop

tx ready

Pull the next workable task.

→

show + context

Read the task and inject the relevant context.

→

implement + verify

Make the change, then run the checks that matter.

pass → tx done

Complete the task and let tx unblock any dependents.

fail → fix or block

Keep iterating or explicitly block the task with the current issue.

Pull one ready task, inspect it, implement, and verify. If nothing is ready, stop. If verification fails, fix or block before trying again.

Installation

Install the standalone binary (no runtime dependencies):

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

Or via npm (requires Bun runtime):

npm install -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": "bunx",
      "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

Optional agent onboarding scaffolds:

tx init --claude            # generated .claude/skills bundle
tx init --codex             # generated .codex/skills bundle + .codex/rules
tx init --claude --codex    # scaffold both generated bundles
tx init --watchdog          # later only: watchdog scripts + launcher + service templates
tx init --watchdog --watchdog-runtime codex

Plain tx init now includes an onboarding step where you choose the exact Claude and Codex tx skills to install. If you pass --claude or --codex, tx skips the prompt and installs the full default bundle for that runtime.

tx init --claude and tx init --codex install generated skill bundles, not legacy top-level CLAUDE.md or AGENTS.md shims. Use tx skills to inspect the bundle model and tx skills sync to refresh installed tx-managed skills later without removing unrelated custom skills.

This creates a .tx/ directory:

.tx/
├── tasks.db           # SQLite database (gitignored)
├── config.toml        # Project configuration with annotated defaults
├── stream.json        # Stream identity (created on first tx sync export)
└── streams/           # Event log directories (created on first tx sync export)

Configuration

tx init generates .tx/config.toml with commented defaults for every setting. Edit it to customize behavior:

[docs]
path = "specs"                             # Where tx doc files live

[memory]
default_dir = "docs"                       # Default dir for tx memory add

[cycles]
agents = 3                                 # Parallel scan agents per cycle
model = "claude-opus-4-6"                  # LLM model for scan agents

[dashboard]
default_task_assigment_type = "human"      # Default assignee: "human" | "agent"

[pins]
target_files = "CLAUDE.md, AGENTS.md"      # Files that tx pin sync writes to
block_agent_done_when_task_id_present = true  # Block agent completion for pin-linked tasks by default

See the generated file for full documentation on each setting, or the relevant primitive docs linked in the comments.

Recommended First Path

If you are new to tx, start with the CLI even if you eventually want MCP, SDK, or API usage. The goal is to get one clean loop working before you absorb the rest of the surface area.

Day 1: Finish One Task Loop

tx init --codex                  # or: tx init --claude, or plain tx init
tx add "Write auth PRD" --json
tx add "Implement auth flow" --json
tx dep block <implement-task-id> <prd-task-id>
tx ready
tx show <prd-task-id>
tx done <prd-task-id>
tx ready
tx sync export

This proves the core of tx is working:

state lives in .tx/tasks.db
dependencies affect tx ready
tx done advances the queue
tx sync export materializes git-friendly stream logs

Day 2: Add The Docs-First Spec Loop

Once the task loop feels normal, add the spec loop:

tx doc add prd auth-flow-prd --title "Auth Flow PRD"
tx doc add design auth-flow-design --title "Auth Flow Design"
tx doc link auth-flow-prd auth-flow-design
# add or update tests in your repo with [INV-*], _INV_*, @spec, or .tx/spec-tests.yml mappings
tx spec discover
tx spec status --doc auth-flow-design
tx decompose auth-flow-design --dry-run
tx decompose auth-flow-design
vitest run --reporter=json | tx spec batch --from vitest
tx spec complete --doc auth-flow-design --by you

Use the spec primitives like this:

tx decompose: turn a stable design doc into a first-pass task graph
tx spec fci: compact machine score for agents and automation
tx spec status: human-readable blocker view for one scope
tx spec health: repo rollup, not part of the minimum day-1 loop

Add More Surface Area Later

After the two loops above are working, then decide whether you actually need:

MCP or Agent SDK integration
claim for parallel workers
auto guard, auto verify, auto label, auto gate, and auto reflect
optional watchdog supervision only if you need unattended long-running loops

Optional: Watchdog Later

Most users should skip this on their first pass. Watchdog onboarding is explicit opt-in and default-off. tx init alone does not enable detached supervision.

Use watchdog when you need:

Long-running unattended RALPH loops
Automatic restart and health checks for Codex/Claude loops
Automatic reconciliation of stale runs and orphaned active tasks

Skip watchdog when you only run short, interactive sessions.

Enable watchdog during init:

tx init --watchdog --watchdog-runtime auto

Runtime mode behavior:

Mode	Behavior
`auto`	Enables only runtimes available in `PATH`; if none are available, scaffolds assets with `WATCHDOG_ENABLED=0`
`codex`	Requires `codex` CLI in `PATH` or exits with actionable error
`claude`	Requires `claude` CLI in `PATH` or exits with actionable error
`both`	Requires both CLIs in `PATH` or exits with actionable error

Watchdog scaffolding adds:

scripts/ralph-watchdog.sh
scripts/ralph-hourly-supervisor.sh
scripts/watchdog-launcher.sh
.tx/watchdog.env
ops/watchdog/com.tx.ralph-watchdog.plist
ops/watchdog/tx-ralph-watchdog.service

Initial rollout check:

./scripts/watchdog-launcher.sh start
./scripts/watchdog-launcher.sh status
tail -n 50 .tx/ralph-watchdog.log

For generated bundles, manual Ralph workflows, and detached service setup, see:

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 dep 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)

// Attach shared context for a task group
await tx.tasks.setGroupContext(task.id, "Shared auth rollout context")

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_dep_block`	Add a dependency
`tx_group_context_set`	Set task-group context
`tx_group_context_clear`	Clear task-group context
`tx_show`	View task details
`tx_memory_context`	Get relevant memory for a task
`tx_memory_search`	Search memory documents
`tx_memory_source_add`	Register directory for indexing
`tx_memory_index`	Index all sources
`tx_pin_set`	Set a persistent pin
`tx_pin_get`	Get a pin by ID
`tx_pin_list`	List all pins
`tx_auto_guard_set`	Set task creation limits
`tx_auto_guard_show`	Show current guards
`tx_auto_guard_check`	Check if creation would pass limits
`tx_auto_gate_create`	Create a HITL phase gate
`tx_auto_gate_approve`	Approve a gate
`tx_auto_gate_revoke`	Revoke a gate
`tx_auto_gate_check`	Check if gate is approved
`tx_auto_gate_status`	Get full gate state
`tx_auto_gate_list`	List all gates
`tx_auto_gate_rm`	Remove a gate
`tx_auto_label_add`	Create a label
`tx_auto_label_delete`	Delete a label
`tx_auto_label_assign`	Assign label to task
`tx_auto_label_unassign`	Remove label from task
`tx_auto_label_list`	List all labels
`tx_auto_verify_set`	Attach verification command to task
`tx_auto_verify_run`	Run verification command
`tx_decompose`	Preview or materialize a task graph from a design doc
`tx_spec_discover`	Discover invariant-to-test mappings
`tx_spec_link`	Manually link an invariant to a test
`tx_spec_unlink`	Remove an invariant-to-test mapping
`tx_spec_tests`	List tests linked to an invariant
`tx_spec_invariants_for_test`	Reverse lookup invariants for a test ID
`tx_spec_gaps`	List uncovered invariants
`tx_spec_fci`	Compute Feature Completion Index and phase
`tx_spec_status`	Show quick phase/FCI/gap summary
`tx_spec_matrix`	Show full spec traceability matrix
`tx_spec_record_run`	Record a single test run result
`tx_spec_batch_run`	Ingest framework/generic batch results
`tx_spec_complete`	Record human COMPLETE sign-off
`tx_auto_reflect`	Session retrospective with signals
`tx_msg_gc`	Garbage collect old messages

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/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Implement auth"}'

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

# Complete a task as an agent (default path)
curl -X POST http://localhost:3456/api/tasks/tx-abc123/done \
  -H "x-tx-actor: agent"

# Complete a task as a human operator
curl -X POST http://localhost:3456/api/tasks/tx-abc123/done \
  -H "x-tx-actor: human"

Task update and completion endpoints treat requests as agent actions unless you send x-tx-actor: human. This matters for gate-linked tasks: when a pin carries a task ID and [pins].block_agent_done_when_task_id_present = true (the default), agent callers cannot mark that task done.

Need A Real Human Review Loop?

For the full pattern where a gate stores taskId, the human approves the gate, and only the human can close the linked review task, see tx gate. That page includes complete CLI and REST worker loops.

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
n/a	`TX_API_KEY`	n/a	API key for authentication (optional)

For REST task updates and completion:

Use x-tx-actor: agent for automated clients.
Use x-tx-actor: human for dashboard-style or manual operator actions.
If you omit the header, tx treats the request as agent.

Memory & File-Based Knowledge

tx provides a headless search system for markdown files. Use it to index and retrieve knowledge from your codebase:

# Register a directory of markdown files
tx memory source add ./docs

# Index all markdown files in registered sources
tx memory index

# Search for knowledge by keyword or semantic similarity
tx memory search "authentication"

# Display a specific document
tx memory show mem-abc123

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

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

// Register and index
await tx.memorySourceAdd('./docs', 'Project Docs')
await tx.memoryIndex()

// Search
const results = await tx.memorySearch({ query: 'authentication' })
for (const doc of results) {
  console.log(`[${doc.relevanceScore.toFixed(2)}] ${doc.title}`)
}

// Show a document
const doc = await tx.memoryDocumentGet('mem-abc123def456')

{ "tool": "tx_memory_source_add", "arguments": { "dir": "./docs" } }
{ "tool": "tx_memory_index", "arguments": {} }
{ "tool": "tx_memory_search", "arguments": { "query": "authentication" } }
{ "tool": "tx_memory_show", "arguments": { "id": "mem-abc123def456" } }

# Register a source directory
curl -X POST http://localhost:3456/api/memory/sources \
  -H "Content-Type: application/json" \
  -d '{"dir": "./docs"}'

# Index all sources
curl -X POST http://localhost:3456/api/memory/index

# Search
curl "http://localhost:3456/api/memory/search?query=authentication"

# Show a document
curl http://localhost:3456/api/memory/documents/mem-abc123def456

The memory system is perfect for:

Storing design docs, architecture decisions, and runbooks
Indexing README files, guides, and inline documentation
Semantic search across your knowledge base
Automatic context injection for related tasks

The memory system captures both file-based knowledge across your project and task-specific insights.

Your First Agent Loop

The simplest agent loop pulls tasks one at a time:

#!/bin/bash
AGENT_CMD=${AGENT_CMD:-codex}  # or: claude
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 your agent work on it
  "$AGENT_CMD" "Your task is $TASK. Run 'tx show $TASK' for details. When done, run 'tx done $TASK'"
done

echo "All tasks complete!"

With Bounded Autonomy

Add guards, verification, and phase scoping for production loops:

#!/bin/bash
# Set up guardrails
tx auto guard set --max-pending 30 --max-depth 3 --enforce

# Phase 1: Discovery (scoped by label)
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 (with verification gates)
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

# Check session health
tx auto reflect --json | jq '.signals'

Store and Retrieve Knowledge

As you work, capture knowledge that should persist:

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

# Search learnings
tx memory search "authentication" -t learning

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

Sync with Git

tx stores runtime state in SQLite and syncs via append-only stream event logs:

# Export event logs
tx sync export

# Import event logs (e.g., after git pull)
tx sync import

Add to your workflow:

# Before committing
tx sync export && git add .tx/stream.json .tx/streams

# After pulling
git pull && tx sync import

Example Orchestration Patterns

Parallel Agents

Run multiple agents pulling from the same queue:

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

Human-in-Loop

Agent proposes, human approves:

AGENT_CMD=${AGENT_CMD:-codex}  # or: claude
task=$(tx ready --json --limit 1 | jq -r '.[0].id')
"$AGENT_CMD" "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
"$AGENT_CMD" "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."

File-Based

Export tasks to a markdown file and let the agent read it directly. No CLI polling needed:

AGENT_CMD=${AGENT_CMD:-claude}  # or: codex
while true; do
  tx md-export                    # materialize ready tasks to .tx/tasks.md
  "$AGENT_CMD" "Read .tx/tasks.md and complete the highest priority task. When done, run: tx done <id>"
done

Options: --watch for auto-regeneration, --include-context to enrich with memory, --filter all to include every status.

Project Structure

your-project/
├── .tx/
│   ├── tasks.db           # SQLite (gitignored)
│   ├── config.toml        # Project configuration
│   ├── stream.json        # Local stream identity
│   └── streams/           # Append-only sync event logs
├── CLAUDE.md              # Claude instructions (optional)
├── AGENTS.md              # Codex instructions (optional)
├── .claude/skills/        # Generated Claude skill bundle (optional)
├── .codex/skills/         # Generated Codex skill bundle (optional)
├── .codex/rules/          # Codex command policy rules (optional)
└── ...your code

Next Steps

You now have tx running. Keep moving in this order so each step builds on the last one:

Task Management: stay with Primitives and focus on ready, done, dep block, show, and sync.
Spec-Driven Development: continue into tx doc, tx spec, and tx decision.
Memory & Context: add tx memory and tx pin once you want durable context.
Bounded Autonomy: add tx auto label, tx auto guard, tx auto verify, tx auto reflect, and tx auto gate.
Coordination: add tx claim, channel messaging via tx msg inbox, and shared group context when multiple actors are involved.
Observability: add tx trace, tx spec health, and the Headful Experience when you need repo-level visibility.

If you later need generated agent bundles or manual long-running loops, continue with tx skills and Ralph Loop.

If you later need detached supervision and recovery playbooks, use the Watchdog Runbook.

Interface-specific deep dives:

Agent SDK: build your own TypeScript agents.
tx ready: readiness detection details.
tx auto label: ready queue scoping by phase.
tx auto guard: task creation limits.
tx auto verify: machine-checkable done criteria.
tx auto reflect: session retrospective and signals.
tx auto gate: human-in-the-loop phase approvals.
tx sync: git synchronization behavior.

Quick Reference

# Tasks
tx add <title>              # Create task
tx ready                    # List unblocked tasks
tx done <id>                # Complete task
tx dep block <id> <blocker>  # Add dependency
tx dep tree <id>            # Show hierarchy
tx show <id>                # View task details
tx md-export               # Export tasks to markdown file
tx group-context set <id> <context>   # Attach shared task-group context
tx group-context clear <id>           # Clear shared task-group context

# Memory
tx memory source add <dir>  # Register markdown directory
tx memory index             # Index all sources
tx memory search <query>    # Search documents
tx memory add <content>        # Store a learning
tx memory search <query>       # Search memory
tx memory context <task-id>    # Get relevant context

# Bounded Autonomy
tx auto label add "phase:discovery"      # Create a label
tx auto label assign <id> "phase:discovery"  # Assign label to task
tx ready --label "phase:discovery"  # Scope ready queue by label
tx auto guard set --max-pending 30       # Set task creation limits
tx auto verify set <id> "bun test"       # Attach verification command
tx auto verify run <id>                  # Run verification
tx auto reflect                          # Session retrospective
tx auto reflect --analyze                # With LLM analysis
tx auto gate create docs-to-build --phase-from docs_harden --phase-to feature_build
tx auto gate check docs-to-build         # exit 0 approved, 1 blocked

# Sync
tx sync export              # Materialize current state into stream event logs
tx sync import              # Apply stream event logs into SQLite

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

Getting Started

On this page