TX v0.3.6

Human-scale AI Augmentation / Orchestration Hydra

Humans Yeeting Directional Recursive Alchemy

• Quick Start
• What is TX
• Usage
• Responses
• Features
• Architecture
• Observability
• Included Meshes
• Documentation
• Philosophy
• Dependencies
• Troubleshooting
• Sibling Projects

Quick Start

tx uses dontAsk permission mode with workDir boundary enforcement — no Docker required. For unrestricted access, use tx start --god-mode.

npm install -g tx-ai

Or install from source:

git clone git@github.com:eighteyes/tx.git
cd tx
npm install && npm link

Then, from any project directory:

# authenticate claude first
tx start

> "Research a report about pelicans riding bikes"
...wait... the next bit is injected by tx.
> Read and follow the instructions in .ai/tx/msgs/...

AI: Your report is available at...

# steps to quit
# to exit tx ( tmux, /exit just leaves to shell )
Cntl-B d

What is TX

Create and collaborate with distributed, observable, composable agentic AI workflows using plain language, tooling and workspaces, via a conversational interface. Provide for reliability using logical wrappers around non-deterministic LLM calls.

Terms

• mesh — a collection of agents with a defined workflow
• message — core unit of interaction between meshes and agents
• core — the session identifier you use to interact with the tx system

After install, run tx start in a new or existing project directory. You drop into a claude-code environment wrapped by tmux with a status bar. Use plain language — "make a hypothesis about bird migration", "add a feature to support xml workflows" — or invoke meshes explicitly with "ask brain about project structure".

The core agent writes a file with frontmatter formatting, which triggers the agentic mesh. The file system is the API for communication. When complete, or if more information is needed, that agent writes a file which is injected into the core session for your review.

Usage

Make a new mesh

> tx start

# -- wait for launch --

> build a mesh that fixes a list of bugs, `bug-hunt`: ingests a list of bugs,
> use haiku to batch into groups, fan-out and iterates on each batch
> through [ examine > fix ] stages, on fan-in, validate against original bug list.

# -- wait for completion --

> run bug-hunt on @buglist.csv

Borrow ideas

> karpathy's llm council looks neat, can you make one for me?

Chain meshes

> research what it takes to run a coffee shop, build agents to help me manage one

Responses

Mesh agents interact with your core session in the following ways. --inbox= and global config provide override options.

hook — new messages are injected into context automatically

inject — (default) direct response added to your session, can be triggered explicitly

ask — new messages must be retrieved with tx inbox

Features

• Claude Code SDK uses your current authentication to run agents in isolation.
• Intents drive behavior — say "code this" and it launches a developer agent.
• Immutable message logs provide observability between core agent and downstream.
• Configuration-driven collections of agents called meshes.
• Mesh message routing protocols provide for agent-driven workflows and HITL.
• Maintain parallel agent sessions from ONE conversation.
• Chain agent outputs with plain language — "research pain points around (topic) and plan a software project based off your findings".
• Know integration: product & software knowledge graph for project planning and execution.

Mesh Configuration

Option	Description
agents	Agent definitions — name, description, prompt file, options
routing	Which agents talk to others and when
manifest	What files to read/write per agent
workspace	Where to save files and artifacts
fsm	(beta) State machine, variables, gates, scripts wrapping agents
guardrails	Settings for automatic steering behavior — see Chaos Contracts
pre/post hooks	Scripts / agents to run before or after the mesh

Router Types

normal — default operation, agent topology is fixed

dispatch — central dispatch agent, for dynamic agent topologies

Chaos Contracts

LLM agents are chaotic by nature — stochastic, not buggy. Prompts that say "STOP", "NEVER", or "ALWAYS" are prayers, not guarantees. TX accepts the chaos and contains it: behavioral constraints are enforced by the runtime, not the prompt. Prompts carry domain knowledge; the chaos contract guarantees invariants.

Contract Clause	Enforcement	Config
Write Gate	Intercepts Write/Edit tool calls. Rejects writes to undeclared files. Error with allowed list 2x, then silent reject, then kill.	manifest.writes in config.yaml
Read Gate	Intercepts Read/Glob/Grep tool calls. Restricts reads to declared inputs.	manifest.reads in config.yaml
Bash Guard	Enforces workDir boundary for Bash commands. Blocks writes outside project dir, catastrophic commands (sudo, rm -rf /, reboot).	guardrails.bash_guard
Max Messages	Dispatcher counts outbound messages per invocation. Hard kill at limit.	max_messages per agent
Route Gate	Dispatcher rejects messages with invalid to: fields against routing table.	routing in config.yaml
Turn Budget	SDK enforces maximum API round-trips per invocation. Prevents runaway agents.	max_turns per agent

Principle: If a constraint can be enforced by the runtime, remove it from the prompt. Save tokens, eliminate a class of bugs.

See Guardrails Reference for full configuration details.

Architecture

As a matter of convention, tx stores all AI tooling information in .ai and hopes that the vendor community will stop polluting our project roots with their hidden folders.

┌─────────────────────────────────────────────────────────────┐
│ Core (Claude CLI in tmux)                                   │
│  - Interactive user session                                 │
│  - Writes task messages to .ai/tx/msgs/                     │
│  - Receives responses via message injection                 │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Consumer (chokidar)                                         │
│  - Watches .ai/tx/msgs/ for new files                       │
│  - Parses frontmatter → queues messages                     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Queue (SQLite)                                              │
│  - messages table: from, to, type, payload                  │
│  - sessions table: agent_id → conversation_id               │
│  - tasks table: id, status, assigned_to, headline           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Dispatcher                                                  │
│  - Polls queue for task messages                            │
│  - Spawns SdkRunner for each worker                         │
│  - Tracks active workers                                    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ SdkRunner (Claude Agent SDK)                                │
│  - Calls Claude programmatically                            │
│  - Resumes previous conversations                           │
│  - Stores session ID after completion                       │
└─────────────────────────────────────────────────────────────┘

Observability

Use a new terminal session, run from the same folder as tx.

• tx trace — view message trace
• tx logs — see system-level processes
• tx spy — watch agent outputs and tasks

Included Meshes

Meshes can be triggered by intent or by directly stating their name.

• brain — Manages project information and know system.
• dev — Basic developer workflow.
• research — 4-agent basic researcher.
• deep-research — 6-agent research with theorizer/disprover loop. Use "theory" or "hypothesis" in your prompt as intent.

See Mesh List for the complete list of meshes.

Documentation

• Guardrails Reference — write gate, read gate, bash guard, routing errors, max turns/messages
• Permissions & Security — dontAsk mode, tool access, workDir boundary, god mode
• Message Format — frontmatter fields, routing, message types
• Mesh List — complete list of available meshes
• Attributions — borrowed techniques and novel contributions

Philosophy

Subagents and skills are fantastic, but they interrupt the conversation and are not invoked as readily as desired. Context pollution is considerable and detracts from the ability to steer the AI. There is also not enough tooling around them for getting consistent, reproducible, composable behavior.

tx is an Augmented Thinking surface area for multiplexed AI interaction. Automation is well covered in the tooling world — we are not aiming to only automate (tx run supports headless operation). We are aiming to extend individual information-processing capability exponentially, using AI as leverage. What matters is not the quantity of tokens consumed, but the quality of outputs, as human attention is the bottleneck for review and completion.

By removing implementation details from your core conversation, your mind is free to operate at a higher, more strategic level, explore tangential ideas with HITL loops to help steer the meshes when they are not clear. You don't have to context switch to change what your AI is working on.

The system takes care of state and behavioral steer-by-wire, isolating each agent with precisely the information and direction it needs. Mesh agents run about 1k tokens when in use.

Design decisions

• We write to files because it is the most natural behavior for a coding AI to send information. Other experiments with tooling proved less effective.
• We use a centralized, immutable log to provide for observability and recovery.
• We use tmux to provide for injections into the active Claude Code session, and for the task display.

Dependencies

• node (recommended: Node >= 20.19.0)
• Authenticated Claude Code
• tmux

Windows notes — If npm install fails during native rebuilds, ensure you are on Node >= 20.19.0 (via nvm-windows is fine).

Troubleshooting

• tx suppresses stdout/stderr so it doesn't interrupt the session. See error messages with tx logs.
• Sometimes claude and tmux stop playing together nicely (gibberish output). Try a tmux reset with Ctrl-B, r. If that doesn't work, Ctrl-C to exit claude, Ctrl-B, d and run reset.

Sibling Projects

• know — product-driven software development knowledge graph
• tx-lite — inter-agent, cross-project local messaging. tx and claude sessions can communicate.
• safe-claude — quick docker sandbox for agentic development