tx

Primitives, not frameworks. Headless, local infrastructure for AI agents.

tx gives you a small set of reusable primitives for task state, docs-first specs, memory, coordination, and observability. You keep the orchestration loop.

Install

# Standalone binary (recommended)
curl -fsSL https://raw.githubusercontent.com/jamesaphoenix/tx/main/install.sh | sh

# Or via npm (requires bun)
npm install -g @jamesaphoenix/tx-cli

Start Small

The recommended first path is:

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

Most users should start with just the first two.

Day 1: Task Management

tx init --codex                  # or: --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 basic loop:

• the queue works
• dependencies affect readiness
• completion advances the queue
• state exports cleanly to .tx/streams

Day 2: Spec-Driven Development

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 with [INV-*], _INV_*, @spec, or .tx/spec-tests.yml
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 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

Human-in-Loop Example

task=$(tx ready --limit 1 --json | jq -r '.[0].id')
codex "Read AGENTS.md. 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
codex "Read AGENTS.md. For task $task: execute the approved ready work from the linked PRD/DD docs and keep tx updated."

The Six Layers

1. Task Management

Core queue and persistence:

• tx init
• tx add
• tx ready
• tx show
• tx done
• tx dep block
• tx sync

2. Spec-Driven Development

Docs-first intent and closure:

• tx doc
• tx decompose
• tx spec
• tx decision

3. Memory & Context

Durable knowledge and prompt context:

• tx memory
• tx pin

4. Bounded Autonomy

Controls for agents with more freedom:

• tx auto label
• tx auto guard
• tx auto verify
• tx auto reflect
• tx auto gate

5. Coordination

Multi-worker and multi-actor primitives:

• tx claim
• tx msg send / tx msg inbox
• tx group-context

6. Observability

Operational visibility once the earlier layers are in place:

• tx trace
• tx spec health
• tx diag stats
• dashboard

Interfaces

| Interface | Best For | |-----------|----------| | CLI | Shell scripts, human operators, local loops | | MCP Server | Claude Code, Cursor, IDE integrations | | TypeScript SDK | Custom Node/Bun agents | | REST API | Language-agnostic HTTP clients | | Dashboard | Visual monitoring and management |

Optional Later

Watchdog is intentionally not part of the main getting-started path.

Use it only if you need detached, long-running supervision:

tx init --watchdog --watchdog-runtime auto
./scripts/watchdog-launcher.sh start

Runbook:

• Watchdog Runbook

Why tx

| | Native Tasks | Static Agent Docs | tx | |---|---|---|---| | Persistence | Session-scoped | Manual file edits | SQLite + git-backed streams | | Multi-agent safety | Easy collisions | Manual coordination | Claims, dependencies, messaging | | Intent tracking | Weak | Weak | Docs-first specs + decision capture | | Knowledge reuse | Lost each session | Static dump | Searchable memory + pins | | Orchestration | Fixed by tool | None | You own the loop |

Docs

• Getting Started
• Primitives
• Agent SDK
• PRDs and Design Docs

Principle

tx should stay small.

It is not an agent framework, not a hosted memory product, and not a prescribed workflow. It is a local set of primitives you can compose into your own loop.