Loading...
How CmuxLayer — Terminal Agent Lifecycle MCP works
21 tools organized into three layers. Layer 1: 11 core surface tools for terminal pane control (list, split, read, send, send_key, rename, status, progress, notify, close, browser). Layer 2: 8 agent lifecycle tools (spawn, stop, send_to, read_output, wait_for, wait_for_all, list, get_state). Layer 3: 2 V2 facade tools (interact + kill) that consolidate all agent operations into a clean, flat API.
Surface Layer
11 core tools
Agent Layer
8 lifecycle tools
V2 Facade
interact + kill
Surface Layer
11 core tools
Agent Layer
8 lifecycle tools
V2 Facade
interact + kill
Each spawned agent transitions through a deterministic state machine: spawning → booting → ready → working → done. Boot detection uses screen content polling to determine when the CLI has finished loading. State transitions are event-driven — wait_for blocks until the target state is reached. Stale agents are detected via PID liveness checks.
Spawning
tmux pane created
Booting
CLI loading
Ready
Boot detected
Working
Prompt sent
Done
Output extracted
Spawning
tmux pane created
Booting
CLI loading
Ready
Boot detected
Working
Prompt sent
Done
Output extracted
Without lifecycle tracking, orchestrating multiple agents is guesswork. The state machine lets OrcClaude spawn 5 agents, wait_for each to reach 'ready', then send prompts — all with deterministic ordering.
CmuxLayer communicates with cmux via a Unix domain socket, achieving 1,423x speedup over CLI subprocess spawning. Every tool call serializes to a JSON command, sends it through the socket, and receives a typed response. The socket path is auto-discovered from the CMUX_SOCKET environment variable or defaults to the standard cmux socket location.
// Socket command flow
const socket = net.connect(CMUX_SOCKET);
socket.write(JSON.stringify({
type: "new_split",
direction: "horizontal",
command: "claude --dangerously-skip-permissions"
}));
// Response: { id: "surface-42", ok: true }
// 1,423x faster than: child_process.exec("cmux split ...")Native MCP over Unix socket — no CLI subprocess overhead
The browser_surface tool opens Playwright-controlled browser instances as cmux panes. A single tool with 8 action types: open (launch browser), navigate (go to URL), snapshot (capture visible state), click (element interaction), type (text input), eval (run JavaScript), wait (element/timeout), and url (get current URL). Enables visual verification alongside terminal agents in the same orchestration flow.
Open
Launch Playwright
Navigate
Go to URL
Snapshot
Capture state
Interact
Click + type
Evaluate
Run JavaScript
Open
Launch Playwright
Navigate
Go to URL
Snapshot
Capture state
Interact
Click + type
Evaluate
Run JavaScript
Repository names are sanitized before shell execution — only alphanumeric characters, hyphens, underscores, and dots pass through. Agent IDs include random suffixes to prevent collision when spawning multiple agents for the same repo. All 21 tools validate input via Zod schemas. Mode enforcement: manual mode makes all mutating tools read-only. Agent quality tracking (unknown → verified → suspect → degraded) lets orchestrators filter unreliable output.