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)

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

Mode Model

Two axes per surface:

• control: autonomous (full access) or manual (read-only for mutating tools)
• intent: chat or audit

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:

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:

Testing

bun run test        # 230 tests via vitest
bun run typecheck   # Type checking

Development

bun install
bun run dev         # Run with tsx (hot reload)
bun run build       # Compile TypeScript
bun run 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. Built by @EtanHey.