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            # CLAUDE.md + .claude/skills
tx init --codex             # AGENTS.md + .codex/agents
tx init --claude --codex    # scaffold both
tx init --watchdog          # later only: watchdog scripts + launcher + service templates
tx init --watchdog --watchdog-runtime codex

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 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 --title "Auth Flow"
# 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
vitest run --reporter=json | tx spec batch --from vitest
tx spec complete --doc auth-flow --by you

Use the spec primitives like this:

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
guard, verify, label, gate, and 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 detached service setup (launchd/systemd), rollback, stale PID cleanup, and troubleshooting, see:

Watchdog Runbook

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)

// 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_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_guard_set`	Set task creation limits
`tx_guard_show`	Show current guards
`tx_guard_check`	Check if creation would pass limits
`tx_verify_set`	Attach verification command to task
`tx_verify_run`	Run verification command
`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_reflect`	Session retrospective with signals

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 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 verify run $task && tx done $task"
done

# Check session health
tx 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" "Plan implementation for $task" > plan.md
echo "Review plan.md, then press Enter to continue..."
read
"$AGENT_CMD" "Execute plan.md"
tx done $task

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/               # Claude skills/hooks (optional)
├── .codex/agents/         # Codex agent profiles (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, 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 label, tx guard, tx verify, tx reflect, and tx gate.
Coordination: add tx claim, channel messaging via tx 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 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 label: ready queue scoping by phase.
tx guard: task creation limits.
tx verify: machine-checkable done criteria.
tx reflect: session retrospective and signals.
tx 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 block <id> <blocker>     # Add dependency
tx 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 label add "phase:discovery"      # Create a label
tx label assign <id> "phase:discovery"  # Assign label to task
tx ready --label "phase:discovery"  # Scope ready queue by label
tx guard set --max-pending 30       # Set task creation limits
tx verify set <id> "bun test"       # Attach verification command
tx verify run <id>                  # Run verification
tx reflect                          # Session retrospective
tx reflect --analyze                # With LLM analysis
tx gate create docs-to-build --phase-from docs_harden --phase-to feature_build
tx 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