cmux-agent-mcp

CMUX MCP Server — a programmable terminal control plane for multi-agent AI workflows.

Turns CMUX into a remote-controllable terminal multiplexer that any AI coding CLI can be orchestrated through. One orchestrator agent spawns, monitors, and communicates with any number of AI agents running in parallel across multiple projects.

What This Does

• Spawn AI agents in CMUX workspaces — Claude Code, Gemini CLI, Codex CLI, OpenCode, Goose
• Inject prompts into running agent sessions as if a human typed them
• Read output from any pane — passive (fast) or deep (asks agents for status)
• Orchestrate — send different plans to different agents in one call
• Manage workspaces — create, rename, reorder, move between windows
• Split panes — horizontal, vertical, grid layouts, drag-to-split
• Browser automation — open URLs, navigate, snapshot DOM, evaluate JS, click/fill/type
• Sidebar metadata — status pills, progress bars, log entries
• Notifications — send alerts with blue ring indicators
• Session recovery — save/restore full layouts including CLI session IDs and conversations
• Auto-skip permissions — each CLI's autonomous mode is handled automatically
• Auto-save — sessions are saved automatically after every layout change

Architecture

+---------------------------------------------------+
|         Your AI Agent (Claude, etc.)               |
|                                                    |
|  "Launch 4 agents and distribute tasks"            |
|                       |                            |
|                  MCP Tool Calls                    |
|                       |                            |
+---------------------------------------------------+
|                  cmux-agent-mcp                        |
|              (this MCP server)                     |
|                       |                            |
|              cmux CLI commands                     |
|                       |                            |
+---------------------------------------------------+
|                     CMUX                           |
|                                                    |
|  +-- Sidebar ----+  +-- Tab Bar ---------------+  |
|  | agents        |  | Claude 1 x | ~/p/sensei  |  |
|  | > project-a   |  +-----------------------------+|
|  |   project-b   |  | +--------+ +--------+    |  |
|  |   outputs     |  | | Claude | | Gemini |    |  |
|  |   edit        |  | | Agent  | | Agent  |    |  |
|  +---------------+  | +--------+ +--------+    |  |
|                      | | Codex  | | Shell  |    |  |
|                      | | Agent  | |        |    |  |
|                      | +--------+ +--------+    |  |
|                      +-----------------------------+
+---------------------------------------------------+

Quick Start

Prerequisites

• Node.js (v22.5+)
• CMUX — install via brew tap manaflow-ai/cmux && brew install --cask cmux

Install

One command:

npm install -g cmux-agent-mcp

Install automatically registers the MCP server globally for all AI coding tools:

One install, every project, every tool. Existing config files are merged — other MCP servers won't be touched.

To re-run manually or for per-project setup:

cmux-agent-mcp init              # re-run global setup
cmux-agent-mcp init --project    # per-project setup (current dir)
cmux-agent-mcp init --root /path # per-project setup (specific dir)

Install from source

git clone https://github.com/multiagentcognition/cmux-agent-mcp.git
cd cmux-agent-mcp
npm install --ignore-scripts
npm run build
node build/cli.js init       # register globally

81 MCP Tools

Status & Discovery

Workspace Management

Window Management

Surface (Tab) Management

Pane / Split Operations

Text I/O

Bulk Text Operations

Sidebar Metadata

Notifications

Browser Automation

High-Level Launchers

Session Management

Orchestration Workflow

The typical multi-agent workflow:

1. cmux_launch_agents(cli: "claude", count: 4)
   → Creates a workspace with 4 Claude Code agents in a 2x2 grid

2. cmux_orchestrate(assignments: [
     { surface: "surface:10", text: "Implement the auth module..." },
     { surface: "surface:11", text: "Write tests for the API..." },
     { surface: "surface:12", text: "Refactor the database layer..." },
     { surface: "surface:13", text: "Update the documentation..." },
   ])
   → Each agent receives its specific task

3. cmux_read_all()
   → Check all agents' progress at once

4. cmux_read_all_deep()
   → Ask idle agents to summarize their status

Mixed-CLI orchestration:

cmux_launch_mixed(agents: [
  { cli: "claude", label: "Architect" },
  { cli: "gemini", label: "Reviewer" },
  { cli: "codex",  label: "Implementer" },
])

Session Recovery

Sessions are auto-saved after every layout change. If CMUX crashes or you restart your machine, call cmux_session_recover to recreate everything — including resuming CLI conversations.

CLI Session Resume

Session IDs are detected from each CLI's session storage:

• Claude: ~/.claude/sessions/*.json
• Codex: ~/.codex/sessions/**/rollout-*.jsonl
• Gemini: ~/.gemini/projects.json + ~/.gemini/tmp/*/chats/*.json
• OpenCode: ~/.local/share/opencode/opencode.db (SQLite)
• Goose: goose session list --format json

Auto-Trust & Permissions

When launching agents, cmux-agent-mcp automatically:

• Claude Code: Sets hasTrustDialogAccepted: true in ~/.claude.json
• Gemini CLI: Adds directory to ~/.gemini/trustedFolders.json
• Codex: Adds trust_level = "trusted" to ~/.codex/config.toml
• OpenCode: Sets permission: 'allow' in its config

No permission prompts — agents start working immediately.

ID Reference Format

CMUX uses ref format for IDs: workspace:5, surface:8, pane:3, tab:2, window:1. Always use the ref format, not bare numbers. Use cmux_identify or cmux_list_pane_surfaces to discover refs.

CMUX Hierarchy

Window → Workspace(s) → Pane(s) → Surface(s) → Panel(s)

• Window: macOS window
• Workspace: Sidebar entry (like a "tab group")
• Pane: Split region within a workspace
• Surface: Tab within a pane (terminal or browser)
• Panel: Content inside a surface

Naming Conventions

Platform Support

macOS only — CMUX is a native macOS application.

Testing

The test/full-test-suite.md file contains a comprehensive test plan covering all 81 tools. Give it to any AI coding agent to execute:

Tag test/full-test-suite.md and say "Execute this test suite"

Tests leave all workspaces open for human visual verification before cleanup.

License

PolyForm Strict 1.0.0