README.md
A programmable terminal control plane for multi-agent AI workflows.
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
Install
One command:
npm install -g cmux-agent-mcp
Install automatically registers the MCP server globally for all AI coding tools:
| Config file | For |
|---|---|
~/.claude.json |
Claude Code, Codex |
~/.cursor/mcp.json |
Cursor |
VS Code mcp.json |
VS Code |
~/.gemini/settings.json |
Gemini CLI |
~/.config/opencode/... |
OpenCode |
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
| Tool | Description |
|---|---|
cmux_status |
Check if CMUX is installed/running, show hierarchy summary |
cmux_tree |
Full hierarchy tree of windows, workspaces, panes, surfaces |
cmux_identify |
Context info for focused window/workspace/pane/surface |
cmux_find |
Search across windows and panes by content or title |
cmux_start |
Launch CMUX if not running |
cmux_screenshot |
Capture screenshot of CMUX window |
Workspace Management
| Tool | Description |
|---|---|
cmux_list_workspaces |
List all open workspaces |
cmux_current_workspace |
Get the currently active workspace |
cmux_new_workspace |
Create a new workspace with optional cwd/command |
cmux_select_workspace |
Switch to a specific workspace |
cmux_close_workspace |
Close a workspace and all its panes |
cmux_rename_workspace |
Rename a workspace (changes the sidebar name) |
| `cmux_reorder_wo |
Tools (12)
cmux_statusCheck if CMUX is installed/running and show hierarchy summarycmux_treeFull hierarchy tree of windows, workspaces, panes, and surfacescmux_identifyContext info for focused window/workspace/pane/surfacecmux_findSearch across windows and panes by content or titlecmux_startLaunch CMUX if not runningcmux_screenshotCapture screenshot of CMUX windowcmux_list_workspacesList all open workspacescmux_current_workspaceGet the currently active workspacecmux_new_workspaceCreate a new workspace with optional cwd/commandcmux_select_workspaceSwitch to a specific workspacecmux_close_workspaceClose a workspace and all its panescmux_rename_workspaceRename a workspaceConfiguration
claude_desktop_config.json
{"mcpServers": {"cmux-agent": {"command": "npx", "args": ["-y", "cmux-agent-mcp"]}}}Try it
→List all currently active workspaces and tell me which one is focused.
→Create a new workspace for the project in the current directory and launch a new terminal session there.
→Search for the pane containing the error logs and provide a summary of its content.
→Take a screenshot of the current CMUX layout to document the agent's progress.
→Rename the current workspace to 'feature-development' to keep my project organized.