tx

Primitives, not frameworks. Headless infrastructure for AI agents.

Memory, tasks, and orchestration — you own the loop.

# CLI (global install)
npm install -g @jamesaphoenix/tx-cli

# Library (project dependency)
npm install @jamesaphoenix/tx

The Problem

Your agents lose context between sessions. Tasks collide when multiple agents work in parallel. Learnings vanish into conversation history. You're rebuilding the same infrastructure every project.

The Solution

Composable primitives that handle the hard parts. You keep control of the orchestration.

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

Primitives

Memory

Learnings that persist and surface when relevant.

# Store knowledge
tx learning:add "Use bcrypt for passwords, not SHA256"
tx learning:add "Redis cache invalidation has race conditions" -c database

# Attach learnings to file paths
tx learn "src/auth/*.ts" "Services must use Effect-TS patterns"

# Retrieve via search or task context
tx learning:search "authentication"
tx context tx-abc123  # Get relevant learnings for a task
tx recall "src/auth/hash.ts"  # Recall learnings for a file

Hybrid search (BM25 + vector with RRF fusion) finds relevant knowledge.

Tasks

Dependency-aware task management. Agents only see work they can actually do.

# Create with dependencies
tx add "Implement auth service" --score 800
tx add "Design auth schema" --score 900
tx block tx-impl tx-schema  # impl waits for schema

# Work on what's ready
tx ready                    # Only unblocked tasks
tx done tx-schema           # Completes → unblocks dependents

Full hierarchy support. Epics contain milestones contain tasks contain subtasks.

Coordination

Lease-based claims prevent parallel agents from colliding.

tx claim tx-abc123 worker-1          # Claim with 30-min lease
tx claim tx-abc123 worker-1 --lease 60  # Custom lease duration
tx claim:renew tx-abc123 worker-1    # Extend lease
tx claim:release tx-abc123 worker-1  # Release early

Attempts

Track what approaches have been tried on a task.

tx try tx-abc123 "Used Redux" --failed "Too complex for this use case"
tx try tx-abc123 "Used Zustand" --succeeded
tx attempts tx-abc123  # See all attempts

Docs

Structured documentation as primitives. YAML-based with versioning, locking, and linking.

tx doc add prd auth-system --title "Auth System PRD"
tx doc render           # Generate markdown from YAML
tx doc lock auth-system # Lock doc (immutable)
tx doc link auth-prd auth-dd  # Link PRD to DD
tx doc drift            # Detect stale docs

Invariants

Track and verify project invariants across sessions.

tx invariant list                          # List all invariants
tx invariant show INV-001                  # Show details
tx invariant record INV-001 --passed       # Record check result
tx invariant sync                          # Sync from CLAUDE.md

Cycle Scan

Sub-agent swarm scanning for codebase analysis.

tx cycle --task-prompt "Review auth" --scan-prompt "Find bugs"

Your Loop, Your Rules

We ship example loops, not the loop:

# 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 with claims
for i in {1..5}; do
  (while task=$(tx ready --json --limit 1 | jq -r '.[0].id // empty'); do
    [ -z "$task" ] && break
    tx claim "$task" "worker-$i" || continue
    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
read -p "Approve? [y/n] " && claude "Execute plan.md"
tx done $task

The flow is yours. Serial, parallel, swarm, human-in-loop. Your call.

TypeScript SDK

This package (@jamesaphoenix/tx) is the library entry point. It re-exports everything from @jamesaphoenix/tx-core plus convenience helpers.

import { TaskService, LearningService, makeAppLayer } from "@jamesaphoenix/tx";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const tasks = yield* TaskService;
  const ready = yield* tasks.getReady({ limit: 5 });
  return ready;
});

// Run with the default layer (SQLite-backed)
const layer = makeAppLayer(".tx/tasks.db");
await Effect.runPromise(program.pipe(Effect.provide(layer)));

For a Promise-based HTTP client, use the Agent SDK:

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

const tx = new TxClient({ apiUrl: "http://localhost:3456" });
const ready = await tx.tasks.ready({ limit: 10 });

Why tx?

| | Native Tasks | CLAUDE.md | tx | |---|---|---|---| | Persistence | Session-scoped | File grows forever | Git-native, branch-aware | | Multi-agent | Collisions | Manual coordination | Claim with lease expiry | | Knowledge | Lost each session | Static dump | Hybrid search, contextual retrieval | | Orchestration | None | None | Primitives for any pattern |

Design Principles

• No opinions on orchestration. Serial, parallel, swarm, human-in-loop. Your call.
• Powerful defaults. tx ready just works. So does dependency resolution.
• Escape hatches everywhere. Raw SQL access, JSONL export, custom scoring.
• Framework agnostic. CLI, MCP, REST API, TypeScript SDK. Use what fits.
• Local-first. SQLite + git. No server required. Works offline.

Packages

| Package | Description | |---------|-------------| | @jamesaphoenix/tx | Library entry point (this package) | | @jamesaphoenix/tx-cli | CLI binary (tx command) | | @jamesaphoenix/tx-core | Core services (Effect-TS) | | @jamesaphoenix/tx-types | Shared type definitions | | @jamesaphoenix/tx-agent-sdk | Promise-based HTTP client | | @jamesaphoenix/tx-mcp-server | MCP server (42 tools) | | @jamesaphoenix/tx-api-server | REST API server |

Interfaces

| Interface | Use Case | |-----------|----------| | CLI | Scripts, terminal workflows, agent loops | | MCP Server | Claude Code integration (42 tools) | | REST API | Custom dashboards, external integrations | | TypeScript SDK | Programmatic access from your agents | | Dashboard | Visual monitoring and management |

Quick Reference

# Tasks
tx add <title>              # Create task
tx list                     # List all tasks
tx ready                    # List unblocked tasks
tx show <id>                # View details
tx update <id>              # Update task fields
tx done <id>                # Complete task
tx delete <id>              # Delete task
tx block <id> <blocker>     # Add dependency
tx tree <id>                # Show hierarchy

# Context & Learnings
tx learning:add <content>   # Store knowledge
tx learning:search <query>  # Search learnings
tx context <task-id>        # Contextual retrieval
tx learn <path> <note>      # Attach to file
tx recall [path]            # Query by file

# Coordination
tx claim <id> <worker>      # Lease-based claim
tx claim:renew <id> <worker>  # Extend lease
tx claim:release <id> <worker>  # Release early
tx try <id> <approach>      # Record attempt

# Docs & Invariants
tx doc add <type> <slug>    # Create doc
tx doc render               # Generate markdown
tx invariant list           # List invariants
tx invariant sync           # Sync from CLAUDE.md

# Sync
tx sync export              # SQLite → JSONL (git-friendly)
tx sync import              # JSONL → SQLite
tx sync claude --team <name>  # Push to Claude Code team

# Traces & Utilities
tx cycle                    # Sub-agent swarm scan
tx trace list               # Recent runs
tx stats                    # Queue metrics
tx doctor                   # System diagnostics
tx dashboard                # Launch dashboard

Storage

.tx/
├── tasks.db           # SQLite (gitignored)
├── tasks.jsonl        # Git-tracked
├── learnings.jsonl    # Git-tracked
├── runs.jsonl         # Git-tracked
└── docs/              # YAML doc sources

Local SQLite for speed. JSONL for git sync. Branch your knowledge with your code.

License

MIT