cmuxLayer
EtanHey/cmuxlayer
Orquestração de agentes IA em terminais multiplexados com 33 MCP tools
Ver no GitHubMCP server com 33 ferramentas para orquestração de agentes de IA em terminais multiplexados. Permite que agentes Claude, Codex, Cursor e Gemini se comuniquem, compartilhem estado de telas, e coordenem execução de tarefas sem depender de clipboard manual. Solução completa para gestão de ciclo de vida, detecção de thinking-state e layout de workspace.
Instalação
npx convez-ai EtanHey/cmuxlayer1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenar múltiplos agentes IA para dividir tarefas complexas
- Monitorar e sincronizar estado entre Claude, Codex, Cursor rodando em paralelo
- Automatizar workflows de desenvolvimento com agentes comunicando via terminal
- Gerenciar panes, workspaces e input/output entre sessões de agentes
Veredito

Ferramenta especializada e madura para times que rodam múltiplos agentes IA em paralelo. Resolve um problema real (comunicação entre agentes), com documentação clara e bom suporte a ferramentas. Requer setup de cmux e é indicada para casos avançados de orquestração, não para uso casual.
README
A tradução para o português deste README ainda está na fila.
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: 33 MCP tools that give AI agents programmatic control over terminal workspaces.
Quick Start
npm install -g cmuxlayer
Requires cmux to be running.
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
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 33 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 (33)
All tools ship with ToolAnnotations for automatic safety policy enforcement.
Terminal control — list_surfaces 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 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 (7)
| Tool | What it does |
|---|---|
list_surfaces | List all surfaces across workspaces |
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 (23)
| 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 |
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 # 669 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.