CmuxLayer

What is CmuxLayer about?

CmuxLayer enables AI agents to share terminal workspaces by acting as a clipboard between them. It exposes a suite of 35 MCP tools that let you programmatically split panes, spawn agents, read screen output, monitor agent state, and coordinate multi‑agent workflows.

How to use CmuxLayer?

1. Install – Use Homebrew (macOS) or install via npm:

   npx -y cmuxlayer
   

2. Run – The cmuxlayer command starts an MCP server that connects to a running cmux instance (required). Ensure cmux is installed and active.
3. Configure – Add the server to your MCP client configuration, e.g.:

   [mcp_servers.cmux]
   command = "cmuxlayer"
   

   or for JSON‑based clients:

   {
     "mcpServers": { "cmux": { "command": "cmuxlayer" } }
   }
   

4. Invoke tools – Call MCP tools from Claude Code, Codex, Cursor, VS Code, etc., to manipulate panes, send input to agents, wait for completion, and display notifications.

Key features of CmuxLayer

• Terminal control: list, split, move, reorder, rename, and close surfaces.
• Agent lifecycle management: spawn, monitor, wait, interact, stop, and kill agents.
• Metacommunication: inbox dispatch, state queries, structured output extraction.
• Workspace state: create/select workspaces, set sidebar status/progress, send notifications.
• Screen parsing: read_screen auto‑detects Claude, Codex, Gemini, and Cursor agents and extracts status, model, token count, and context usage.
• Performance: Unix‑socket communication latency ~0.1 ms (≈1,400× faster than CLI fallback).

Use cases of CmuxLayer

• Coordinated testing: Split a pane, run a test suite in one pane while another agent reviews failures.
• Code refactoring loops: Spawn a Claude Code agent to refactor a file, then have a Codex agent run linting on the result.
• Build monitoring: Read build output from a surface, set a sidebar status indicator, and notify the team when the build passes.
• Multi‑agent orchestration: Dispatch tasks to several agents, wait for all to finish, and aggregate their outputs.
• Recovery tooling: Use raw surface tools (send_key, send_command) to revive stuck panes or re‑attach to a lost agent.

FAQ from CmuxLayer

• Do I need to run cmux separately? Yes, CmuxLayer requires a running cmux instance. Install it from its repository and start a session before launching CmuxLayer.
• Which agents are supported? Claude Code, Codex, Gemini CLI, and Cursor agents are auto‑detected. Their metadata (status, model, tokens, context %) is parsed by read_screen.
• What if tools don’t appear in my IDE? Restart the IDE after adding the MCP config and verify the entry (mcpServers.cmux.command = "cmuxlayer"). Use the IDE’s MCP list command to confirm connectivity.
• How does CmuxLayer handle socket failures? It auto‑discovers the cmux Unix socket, falls back to a CLI subprocess if the socket is unavailable, and auto‑reconnects on disconnection.
• Can I customize the socket path? Yes, set the CMUX_SOCKET_PATH environment variable to point to a custom socket location.

cmuxLayer

Your AI agents can't see each other's terminals. One runs in tab 1, another in tab 2 — and you're the clipboard between them. cmuxLayer fixes that: 35 MCP tools that give AI agents programmatic control over terminal workspaces.

Quick Start

brew install etanhey/layers/cmuxlayer       # stable, pinned release
brew install --HEAD etanhey/layers/cmuxlayer # or: dogfood the latest main

This installs the cmuxlayer command (plus cmuxlayer-app-server / cmuxlayer-proxy). Requires cmux to be running. For how the golem fleet wires, versions, and dogfoods it — and the CMUX_SOCKET_PATH instance pin — see docs/releases-and-brew.md.

Add to your MCP config:

Codex CLI / T3 Code

T3 Code inherits MCP servers from the Codex CLI config file at ~/.codex/config.toml (or $CODEX_HOME/config.toml).

[mcp_servers.cmux]
command = "cmuxlayer"

Claude Code, Cursor, VS Code, Claude Desktop

{
  "mcpServers": {
    "cmux": {
      "command": "cmuxlayer"
    }
  }
}

Config locations: Codex CLI / T3 Code ~/.codex/config.toml (or $CODEX_HOME/config.toml) | Claude Code .mcp.json or claude mcp add cmuxlayer -s user -- cmuxlayer | Cursor .cursor/mcp.json | VS Code .vscode/mcp.json | Claude Desktop — see MCP docs for platform-specific paths

What You Can Do

Tell your AI agent things like:

• "Split a pane to the right and run my test suite there"
• "Spawn a Claude Code agent in a new pane to refactor auth.ts"
• "Read the screen of surface:2 and tell me if the build passed"
• "Wait for all agents to finish, then read their output"
• "Set the sidebar status to show our deploy progress"

Under the hood, cmuxLayer exposes 35 MCP tools for terminal control, screen reading, layout management, and multi-agent orchestration. read_screen parses agent metadata (status, model, tokens, context %) for Claude Code, Codex, Gemini, and Cursor.

Agent Routing Workflow

For managed agents, use the agent-first path: list_agents to find the target, send_to to deliver work by agent_id, then wait_for when you need completion. Raw surface tools such as send_input, send_command, and send_key are still available for shells, launch/resume commands, stuck-pane recovery, and explicit terminal UI operations.

See Agent Routing and Handling Workflow for the full operator playbook, including stuck surface recovery and safe /mcp menu reconnects.

MCP Tools (35)

All tools ship with ToolAnnotations for automatic safety policy enforcement.

Terminal control — list_surfaces control_health select_workspace create_workspace new_split new_surface move_surface reorder_surface send_input send_command send_key read_screen rename_tab close_surface browser_surface

Agent lifecycle — spawn_agent new_worktree_split spawn_in_workspace resync_agents send_to send_to_agent wait_for wait_for_all interact stop_agent kill

Metacomm (agent inbox) — dispatch_to_agent inbox_check

Workspace state — list_agents my_agents get_agent_state read_agent_output notify set_status set_progress

Read-only (8)

Tool	What it does
list_surfaces	List all surfaces across workspaces
control_health	Report socket, binary, process, and job-control diagnostics
read_screen	Read terminal output with parsed agent status
get_agent_state	Full state of a tracked agent
list_agents	All agents, with optional filters
my_agents	Children of a parent agent with live screen status
read_agent_output	Structured output between delimiter markers
inbox_check	Inspect an agent's inbox channel: pending messages, monitor liveness, stale dispatches

Mutating (24)

Tool	What it does
select_workspace	Switch the active workspace
create_workspace	Create a new named workspace
new_split	Create a terminal or browser split pane
new_surface	Create a tab in an existing pane
move_surface	Move a surface to another pane or position
reorder_surface	Reorder tabs within a pane
send_input	Send text to a raw surface; use send_to for tracked agents
send_command	Atomically send a command and press return on the same surface
send_key	Send key press (return, escape, ctrl-c, etc.) to a raw surface
rename_tab	Rename a surface tab
notify	Show a cmux notification banner
set_status	Set sidebar status key-value pair
set_progress	Set progress indicator (0.0-1.0)
browser_surface	Interact with browser surfaces
spawn_agent	Spawn a CLI agent and return an agent_id for routing
new_worktree_split	Create or reuse a git worktree and spawn a worker there
spawn_in_workspace	Create a workspace and spawn a multi-agent team into a clean grid
resync_agents	Re-sync the agent registry from live surfaces
dispatch_to_agent	Append a task to an agent's inbox file (deterministic write channel)
send_to	Preferred path for sending text to a tracked agent by agent_id
send_to_agent	Legacy/internal agent send path; prefer send_to
wait_for	Block until agent reaches a target state (defaults to done)
wait_for_all	Block until multiple agents finish
interact	Send interactive input (confirm, cancel, resume)

Destructive (3)

Tool	What it does
close_surface	Close a terminal or browser pane
stop_agent	Gracefully stop an agent
kill	Force-kill agent processes

Supported Agents

CLI	Command	Auto-detected
Claude Code	claude	status, model, tokens, context %
Codex	codex	status, model, context %
Gemini CLI	gemini	status, model, tokens, context %
Cursor	cursor agent	status, model, tokens, context %
read_screen auto-detects agent type and parses metadata from terminal output.

Architecture

AI Agent  ─── MCP ───>  cmuxLayer  ─── Unix socket ───>  cmux
                         ├── Agent engine (spawn → monitor → teardown)
                         ├── Screen parser (5 agent formats)
                         ├── Mode policy (autonomous vs manual)
                         ├── State manager + event log
                         ├── Metacomm READ  — harness JSONL (real tokens/context/model)
                         └── Metacomm WRITE — per-agent inbox file + Monitor dispatch

The socket client connects to cmux via Unix socket. Auto-reconnects on disconnect, falls back to CLI subprocess if socket is unavailable.

Connection	Latency	Speedup
CLI subprocess	~142ms	baseline
Unix socket	~0.1ms	1,423x

Troubleshooting

cmux is not running cmuxLayer requires a running cmux instance. Install it first, then start a cmux session before using cmuxLayer.

Tools not appearing in Codex CLI or T3 Code Restart the client after adding cmuxlayer to ~/.codex/config.toml. If you use a custom Codex home, verify $CODEX_HOME/config.toml contains the same mcp_servers.cmux entry.

Tools not appearing in Claude Code Restart Claude Code after adding the MCP config. Run claude mcp list to verify cmuxlayer is connected.

Socket connection failed cmuxLayer auto-discovers the cmux socket (macOS: ~/Library/Application Support/cmux/cmux.sock). Override with CMUX_SOCKET_PATH if needed.

Testing

bun run test        # 798 tests via vitest
npm run typecheck   # Type checking

Git hooks

Enable project hooks to run the regression gate automatically on git push:

git config core.hooksPath .githooks

This enables .githooks/pre-push, which runs scripts/run_tests.sh and blocks pushes on regression failures.

Development

npm install
npm run dev         # Run with tsx (hot reload)
npm run build       # Compile TypeScript
npm start           # Run compiled output

Contributing

See CONTRIBUTING.md for development setup and PR guidelines.

License

Apache 2.0 — see LICENSE.

---

Part of the Golems AI agent ecosystem. cmuxlayer.etanheyman.com | Built by @EtanHey.