The Terminal That Reads Itself: Inside NTM

How a Go-based orchestrator reverse-engineers AI CLI outputs to manage parallel coding swarms in tmux.

A mechanical eye inspecting a ticker tape and outputting a clean punch card, representing NTM parsing terminal output. — NTM acts as a sensory layer, turning unstructured terminal noise into structured state data.

Key Takeaways

NTM uses heuristic pattern matching to translate unstructured terminal outputs into actionable machine states.
Robot Mode exposes tmux session data through a JSON API to allow agents to recursively manage their own peers.
The system prevents file collisions by isolating parallel agents within dedicated Git worktrees.
Sticky routing ensures task continuity by directing related file edits to the same agent context.

The Blindness of the Command Line

AI coding tools like Claude Code and Codex were built for humans. They emit animated spinners, ANSI colors, and conversational quirks. This creates a problem for automation.

If you pipe an AI CLI into a standard terminal multiplexer, the orchestrator is blind. It has no idea if the agent is working, rate-limited, or stuck waiting for a prompt. NTM (Named Tmux Manager) solves this by reverse-engineering the human interface for machine consumption.

A powerful tmux session management tool for orchestrating multiple AI coding agents in parallel.

- Project README

The Heuristic State Machine

NTM gives the system eyes through patterns.go. This file acts as a regex engine that strips ANSI codes and uses pattern frequency analysis. It determines if an agent is in a "Thinking," "Stalled," or "Rate Limited" state.

Instead of guessing, the parser assigns confidence scores to terminal stream chunks. It looks for structural patterns rather than exact vocabulary.

// Example of structural spinner detection
var ccSpinnerActivePatterns = []*regexp.Regexp{
    regexp.MustCompile(`\S+…\s+\(\d+s\)`),
}

A three-panel interactive diagram showing The State Inference Engine. Left panel: A simulated terminal window streaming text like 'Claude Code> Bunning... (3s)'. Middle panel: A regex filter node that lights up when a specific string passes through. Right panel: A state machine gauge switching from Idle to Working to Rate Limited.

Recursive Orchestration: The Robot Mode

Because NTM knows the exact state of the terminal, it can expose that state via a JSON API. This architectural pivot is called Robot Mode.

NTM projects the tmux state into a queryable SQLite database. By exposing --robot-* flags, an AI agent running inside a pane can query the status of its peers or spawn new workers to parallelize its own tasks.

Classic wooden nesting dolls with mechanical arms operating a switchboard, representing recursive agent control. — Robot mode allows an agent inside the system to manipulate the orchestrator itself.

Preventing Swarm Collisions

Parallel agents inevitably try to edit the same files. NTM introduces Git worktrees for strict isolation.

Each agent receives its own isolated file system view. NTM uses "Sticky Routing" to maintain context affinity, ensuring tasks related to specific files are routed to the agent that already has them in its context window.

The Orchestration Landscape

The AI orchestration space splits between passive monitoring and active control. NTM focuses on active, command-palette-driven tiling logic.

Project	Primary Function	State Inference	Isolation
NTM	Active Orchestration	Heuristic Parsing	Git Worktrees
Codirigent	Desktop Workspace	Native OS Events	Shared Directory
TmuxCC	Passive Monitoring	Heuristic Parsing	None
tcmux	CLI Viewer	Basic Regex	None

Sources: