Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/EtanHey/cmuxlayer.git
cd cmuxlayer
bun install
bun run buildRegister it in Claude Code
claude mcp add cmuxlayer -- node /path/to/cmuxlayer/dist/index.jsReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
cmuxlayer's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Persistent Unix socket connection to cmux for high-performance communication
- Agent lifecycle engine for spawning, monitoring, and teardown of agents
- Parsed agent metadata extraction from raw terminal output
- Support for Claude Channels to push agent status updates
- Mode policy enforcement for autonomous vs manual control
Tools 10
list_surfacesList all surfaces across workspacesnew_splitCreate a new split pane (terminal or browser)send_inputSend text to a terminal surface (with optional enter/rename)send_keySend a key press to a surfaceread_screenRead raw screen text plus parsed agent state from a surfacerename_tabRename a surface tab (with optional prefix preservation)set_statusSet sidebar status key-value pairset_progressSet sidebar progress indicator (0.0-1.0)close_surfaceClose a surfacebrowser_surfaceInteract with browser surfacesEnvironment Variables
CMUXLAYER_ENABLE_CLAUDE_CHANNELSEnables experimental Claude channel notifications for agent lifecycle updatesTry it
Original README from EtanHey/cmuxlayer
cmuxlayer
Terminal multiplexer MCP — multi-agent workspace orchestration for cmux.
233 tests · 1,423x socket speedup · Native MCP in cmux Swift fork · 10 MCP tools · Agent lifecycle engine
cmuxlayer gives AI agents programmatic control over terminal workspaces via MCP. Spawn split panes, send commands, read screen output, manage agent lifecycles — all through typed MCP tools that any MCP-compatible AI client can use.
read_screen returns raw terminal text alongside structured parsed agent metadata for common CLI agents including Claude, Codex, and Gemini. That makes status checks, done-signal detection, token counting, and model extraction available directly through MCP without forcing each client to re-parse terminal output.
Quick Start
git clone https://github.com/EtanHey/cmuxlayer.git && cd cmuxlayer
bun install
bun run build
Add to your editor's MCP config:
{
"mcpServers": {
"cmux": {
"command": "node",
"args": ["/path/to/cmuxlayer/dist/index.js"]
}
}
}
Requires cmux to be installed and running.
Claude Channels Preview
Set CMUXLAYER_ENABLE_CLAUDE_CHANNELS=1 in the server environment and launch Claude Code with --channels <server-name> plus --dangerously-load-development-channels <server-name> during preview. With that enabled, cmuxlayer advertises experimental["claude/channel"] and emits one-way notifications/claude/channel updates when tracked agents are spawned, finish, or error.
See docs/claude-channels-mobile.md for the notification format, OpenClaw pairing patterns worth stealing, and the remaining gaps for a real cmux mobile client.
MCP Tools (10)
| Tool | Description |
|---|---|
list_surfaces |
List all surfaces across workspaces |
new_split |
Create a new split pane (terminal or browser) |
send_input |
Send text to a terminal surface (with optional enter/rename) |
send_key |
Send a key press to a surface |
read_screen |
Read raw screen text plus parsed agent state from a surface |
rename_tab |
Rename a surface tab (with optional prefix preservation) |
set_status |
Set sidebar status key-value pair |
set_progress |
Set sidebar progress indicator (0.0-1.0) |
close_surface |
Close a surface |
browser_surface |
Interact with browser surfaces |
Architecture
AI Agent ─── MCP ───> cmuxlayer
├── Persistent socket connection (1,423x faster than CLI)
├── Agent lifecycle engine (spawn, monitor, teardown)
├── Mode policy (autonomous vs manual control)
├── Event log + state manager
└── Pattern registry for naming conventions
Key Components
| File | Role |
|---|---|
cmux-socket-client.ts |
Persistent Unix socket connection to cmux (1,423x speedup over CLI) |
cmux-client.ts |
CLI wrapper fallback |
server.ts |
MCP tool registration and handlers |
agent-engine.ts |
Agent lifecycle — spawn, monitor, quality tracking |
agent-registry.ts |
Registry of active agents across surfaces |
naming.ts |
Surface naming rules (launcher prefix preservation) |
mode-policy.ts |
Mode enforcement (autonomous = full access, manual = read-only) |
state-manager.ts |
Sidebar state synchronization |
event-log.ts |
Audit trail for all agent actions |
pattern-registry.ts |
Reusable patterns for common workflows |
Mode Model
Two axes per surface:
- control:
autonomous(full access) ormanual(read-only for mutating tools) - intent:
chatoraudit
Set via set_status with reserved keys mode.control / mode.intent.
Socket Performance
cmuxlayer connects to cmux via a persistent Unix socket instead of spawning CLI subprocesses:
| Method | Latency | Throughput |
|---|---|---|
| CLI subprocess | ~142ms | Baseline |
| Persistent socket | ~0.1ms | 1,423x faster |
The socket client auto-reconnects on disconnect and falls back to CLI if the socket is unavailable.
Upstream Contributions
cmuxlayer development has contributed back to cmux:
| PR | Status | What |
|---|---|---|
| #1522 | Open | Fix: background workspace PTY initialization |
| [#1562](https://github.com/ |