by EtanHey
Provides 35 MCP tools for terminal control, screen reading, layout management, and orchestrating multiple AI agents such as Claude, Codex, Gemini, and Cursor within a cmux multiplexed environment.
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.
npx -y cmuxlayer
cmuxlayer command starts an MCP server that connects to a running cmux instance (required). Ensure cmux is installed and active.[mcp_servers.cmux]
command = "cmuxlayer"
or for JSON‑based clients:
{
"mcpServers": { "cmux": { "command": "cmuxlayer" } }
}
read_screen auto‑detects Claude, Codex, Gemini, and Cursor agents and extracts status, model, token count, and context usage.send_key, send_command) to revive stuck panes or re‑attach to a lost agent.cmux instance. Install it from its repository and start a session before launching CmuxLayer.read_screen.mcpServers.cmux.command = "cmuxlayer"). Use the IDE’s MCP list command to confirm connectivity.CMUX_SOCKET_PATH environment variable to point to a custom socket location.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.
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.jsonorclaude mcp add cmuxlayer -s user -- cmuxlayer| Cursor.cursor/mcp.json| VS Code.vscode/mcp.json| Claude Desktop — see MCP docs for platform-specific paths
Tell your AI agent things like:
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.
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.
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
| 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 |
| 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) |
| Tool | What it does |
|---|---|
close_surface |
Close a terminal or browser pane |
stop_agent |
Gracefully stop an agent |
kill |
Force-kill agent processes |
| 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. |
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 |
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.
bun run test # 798 tests via vitest
npm run typecheck # Type checking
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.
npm install
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm start # Run compiled output
See CONTRIBUTING.md for development setup and PR guidelines.
Apache 2.0 — see LICENSE.
Part of the Golems AI agent ecosystem. cmuxlayer.etanheyman.com | Built by @EtanHey.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
An MCP server implementation that provides a tool for dynamic and reflective problem-solving through a structured thinking process.
by danny-avila
Provides a self‑hosted ChatGPT‑style interface supporting numerous AI models, agents, code interpreter, image generation, multimodal interactions, and secure multi‑user authentication.
by block
Automates engineering tasks on local machines, executing code, building projects, debugging, orchestrating workflows, and interacting with external APIs using any LLM.
by RooCodeInc
Provides an autonomous AI coding partner inside the editor that can understand natural language, manipulate files, run commands, browse the web, and be customized via modes and instructions.
by pydantic
A Python framework that enables seamless integration of Pydantic validation with large language models, providing type‑safe agent construction, dependency injection, and structured output handling.
by mcp-use
A Python SDK that simplifies interaction with MCP servers and enables developers to create custom agents with tool‑calling capabilities.
by lastmile-ai
Build effective agents using Model Context Protocol and simple, composable workflow patterns.
by Klavis-AI
Provides production‑ready MCP servers and a hosted service for integrating AI applications with over 50 third‑party services via standardized APIs, OAuth, and easy Docker or hosted deployment.
by nanbingxyz
A cross‑platform desktop AI assistant that connects to major LLM providers, supports a local knowledge base, and enables tool integration via MCP servers.
{
"mcpServers": {
"cmux": {
"command": "npx",
"args": [
"-y",
"cmuxlayer"
],
"env": {}
}
}
}claude mcp add cmux npx -y cmuxlayer