TX-1
Documentation

Getting started

Everything you need to run TX-1 locally and understand what each part does.

Prerequisites

  • macOS — required for Tauri v2 global shortcut (Cmd+K) and the transparent window API
  • Node.js 18+ — for the React frontend build
  • Rust — via rustup.rs. Tauri v2 compiles the Rust shell.
  • Python 3.12 — for the FastAPI sidecar and OR-Tools solver
  • uv — Python package manager. Significantly faster than pip for sidecar dependency resolution.
  • Anthropic API key — used by the Dispatcher (Haiku), Inspector (Haiku), and Strategist (Sonnet) agents

Setup

1. Clone

TX-1 is currently in private development — the repository is not publicly available. Contact us for access.

2. Python sidecar

cd python_app
uv venv --python python3.12 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Start the sidecar (DB auto-seeds on first launch)
uvicorn main:app --port 8765
The sidecar seeds both the Chicago and Amsterdam networks automatically on first launch. You do not need to run any seed scripts manually.

3. React frontend (separate terminal)

cd tx1-terminal
npm install
npm run tauri dev

4. Open

The app launches with a Home screen showing your projects, quick actions, and available networks. Create a project, connect it to a network, and start typing commands in the terminal tab.

The workspace is persistent — projects and tabs are stored in SQLite and survive restarts. On launch, the sidecar sends a WORKSPACE_INIT payload over WebSocket to hydrate the UI.

Workspace & UI

TX-1 organises work into projects, each containing one or more tabs. Tabs can be terminal sessions (connected to a network) or system panels.

Home Screen
Project cards grid, quick actions (Import Data, Connect Tool), and available networks summary. Create or open projects from here.
Project Explorer
Left sidebar. Create, switch, and delete projects. Terminal tabs are nested under the active project with status indicators (idle, working, action required).
Tab Bar
Top of the content area. Each tab connects to a network. The + button opens a network picker. System tabs (Settings, Integrations, Data Import) open from the user menu.
System Panels
Settings — workspace name, default network, solver config. Integrations — connect/disconnect external tools (live toggle via API). Data Import — CSV, API endpoint, or database source types.
User Menu
Top-right avatar dropdown. Opens Settings, Integrations, and (soon) Profile and Keyboard Shortcuts. Full keyboard navigation with arrow keys and Escape.

Terminal Commands

❯ check health→ HEALTH_CHECK
Runs the Inspector agent against the database. Returns a HealthArtifact card with a readiness score (0–100) and a list of issues.
❯ run baseline→ SOLVE_REQUEST
Runs OR-Tools against the Chicago network. Triggers the Auto-Fix loop if INFEASIBLE.
❯ run amsterdam→ SOLVE_REQUEST
Runs OR-Tools against the Amsterdam EU network. Same Auto-Fix loop applies.
❯ reset→ RESET_SCENARIO
Restores WH_CHICAGO_01 capacity to 10,000 units (dirty data). Demo is repeatable.
❯ reset amsterdam→ RESET_SCENARIO
Restores WH_AMSTERDAM_01 capacity to 15,000 units (dirty data).
❯ reset all→ RESET_SCENARIO
Restores both networks simultaneously.
❯ history→ RESEARCH
Shows what the Archivist has stored from past approved fixes.

Demo Flow

The recommended sequence for a live demo or first run:

❯ reset all          # ensure both networks are in dirty state
❯ check health       # show the Inspector finding the constraint violation
❯ run baseline       # Chicago: INFEASIBLE → Sensitivity → InfeasibilityCard
                     # → ⌘↵ to approve → OPTIMAL ($47,880)
❯ run amsterdam      # EU: INFEASIBLE → Sensitivity → InfeasibilityCard
                     # → ⌘↵ to approve → OPTIMAL
❯ history            # Archivist now has 2 approved fixes in memory
❯ reset all          # back to dirty state — ready to demo again
After the first approved fix, subsequent run baseline runs will show the Archivist surfacing that historical fix as context for the Strategist — demonstrating the learning loop.

Key Concepts

LangGraph
A graph-based agent orchestration framework. TX-1 uses a StateGraph where each node does one job and passes a partial state update to the next node. Conditional edges route based on solver output (SUCCESS vs INFEASIBLE). The graph can cycle — apply_fix loops back to solver_engine.
HITL Gate
Human-in-the-Loop approval gate. The graph blocks at this node using a threading.Event until the user explicitly Approves or Dismisses. Nothing touches the database without a human decision. The 5-minute timeout auto-dismisses if the window is left unattended.
ActionCard
A structured JSON payload the backend emits over WebSocket. The React CardRegistry maps the card type string to a React component. Cards are the primary communication mechanism from agents to users.
Dry-Run
Before any SQL patch is shown to the user, the Strategist executes it inside a BEGIN/ROLLBACK transaction and verifies the constraint is resolved. If the dry-run fails, the patch is discarded and the Strategist reformulates. This is the primary hallucination guard.
Archivist
A ChromaDB vector store that persists approved fixes as natural-language documents. On each new violation, the Archivist retrieves the 3 most semantically similar past fixes and injects them into the Strategist's context. The system compounds knowledge over time.
Sensitivity Explorer
A card emitted before the InfeasibilityCard showing 5 capacity scenarios (MINIMUM → MAXIMUM) with headroom % and monthly expansion cost. Navigate with arrow keys. Context before action.
Circuit Breaker
If the Auto-Fix loop fails to resolve infeasibility after 3 iterations (iteration_count > 3), a Manual Review Required card renders and the loop halts permanently. This prevents infinite agent loops on genuinely unsolvable constraints.
Workspace
The persistent layer that organises work. Projects contain tabs; each terminal tab binds to a network. Stored in SQLite (workspace_projects + workspace_tabs). Runtime state (busy, solver status) merges on top.
System Tabs
Non-terminal tabs: Settings, Integrations, Data Import. Opened from the user menu or quick actions. Only one of each type per project — re-selecting focuses the existing tab.
network_id
A column on nodes and lanes tables that partitions the database into independent supply networks. chicago and amsterdam are the two seeded networks. The solver, Strategist, and dry-run all filter by network_id — no cross-network data leakage.

Guardrails

TX-1 is designed for enterprise use where unreviewed data mutations are unacceptable. The following guardrails are non-negotiable:

  • Dry-run before every proposal. No SQL patch reaches the user without being proven feasible in a rolled-back transaction.
  • HITL gate on every mutation. The database is never written to without an explicit human Approve signal. Auto-dismissal after 5 minutes makes no changes.
  • Audit log for all decisions. Every agent-proposed change and human decision is written to audit_log with user_approved=1/0.
  • Context window guard. The Strategist never receives the full database — only schema headers and violation-relevant rows.
  • Immutable master data. The Strategist is prompted to never modify nodes.latitude, nodes.longitude, nodes.type, or the products table. Attempting to do so triggers a high-severity warning card instead.
  • Sidecar localhost-only. The FastAPI sidecar binds to 127.0.0.1 only — no external network exposure.

Troubleshooting

● OFFLINE in the status bar

The WebSocket to the sidecar is down. Ensure uvicorn main:app --port 8765 is running in the python_app directory with the virtualenv active. Check that ANTHROPIC_API_KEY is set in python_app/.env.

Window vanishes immediately on Cmd+K

The global shortcut was firing on both keydown and keyup. This was fixed by the ShortcutState::Pressed guard in lib.rs. If you see this, rebuild the Tauri shell: npm run tauri dev.

run baseline solves immediately (no Auto-Fix loop)

Chicago was previously fixed and the capacity is still at 12,000. Type reset to restore dirty data, then run again.

Strategist failed / JSON parse error

Sonnet occasionally wraps its JSON in markdown fences despite the system prompt. The agent has a fence-stripper that handles this. If it persists, check your API key quota.

ChromaDB telemetry warnings in logs

Harmless. ChromaDB 0.6.x has an internal telemetry API mismatch. It does not affect functionality — the Archivist store and retrieval work correctly.