📦

Cmux

A Model Context Protocol server that provides access to the currently active tab of cmux

0 installs

Trust: 37 — Low

Content

Ask AI about Cmux

I know everything about Cmux. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

cmux-mcp

한국어

MCP server that gives AI agents full control of your cmux terminal.

Let Claude run commands, read output, manage tabs/panes/workspaces/windows, and send control characters in your cmux terminal -- all through the Model Context Protocol. Works in the background. No focus stealing.

Quick Start

Option A: Claude Code Plugin (Recommended)

/plugin marketplace add daegweon/cmux-mcp
/plugin install cmux-mcp@cmux-tools

That's it. The MCP server is configured automatically.

Option B: npx (No build required)

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "npx",
      "args": ["-y", "cmux-mcp"]
    }
  }
}

Restart Claude Code.

Option C: Clone and build

git clone https://github.com/daegweon/cmux-mcp.git
cd cmux-mcp
npm install && npm run build

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Restart Claude Code.

Claude Desktop setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Restart Claude Desktop after saving.

Any MCP client

cmux-mcp communicates over stdio. Point your MCP client to node /path/to/cmux-mcp/build/index.js.

Requirements

macOS
cmux.app installed and running
Node.js 18+
cmux socket control mode set to Automation or Open Access (Settings > Automation > Socket Control Mode)

Tools

cmux-mcp exposes the full cmux CLI as MCP tools. All terminal I/O tools support an optional surface parameter for targeting specific tabs.

Terminal I/O

Tool	Description
`write_to_terminal`	Send commands to the terminal. Enter is appended automatically. Returns new output line count.
`read_terminal_output`	Read the last N lines from the terminal buffer.
`send_control_character`	Send Ctrl+C, Ctrl+Z, Escape, or any control character.

Surface (Tab) Management

Tool	Description
`list_surfaces`	List all tabs in a workspace with IDs and titles.
`new_surface`	Create a new terminal tab.
`close_surface`	Close a specific tab.
`focus_surface`	Focus (activate) a specific tab.
`move_surface`	Move a tab to a different pane, window, or position.
`reorder_surface`	Reorder a tab within its pane.
`rename_tab`	Rename a tab.
`new_split`	Split the current surface into a new pane.
`drag_surface_to_split`	Drag a surface to create a split.
`refresh_surfaces`	Refresh all surfaces.
`surface_health`	Check health of surfaces.

Pane Management

Tool	Description
`list_panes`	List all panes in a workspace.
`new_pane`	Create a new pane (split) with direction.
`focus_pane`	Focus a specific pane.
`resize_pane`	Resize a pane in a given direction.
`swap_pane`	Swap two panes.
`break_pane`	Break a pane out into a new workspace.
`join_pane`	Join a pane into another pane.
`last_pane`	Switch to the last active pane.
`list_panels`	List all panels in a workspace.
`focus_panel`	Focus a specific panel.

Window Management

Tool	Description
`list_windows`	List all windows.
`new_window`	Create a new window.
`close_window`	Close a specific window.
`focus_window`	Focus a specific window.
`current_window`	Show current window info.
`rename_window`	Rename the current window.
`next_window` / `previous_window` / `last_window`	Navigate between windows.
`move_workspace_to_window`	Move a workspace to a different window.

Workspace Management

Tool	Description
`list_workspaces`	List all workspaces.
`new_workspace`	Create a new workspace with optional cwd/command.
`close_workspace`	Close a specific workspace.
`select_workspace`	Switch to a specific workspace.
`rename_workspace`	Rename a workspace.
`current_workspace`	Show current workspace info.
`reorder_workspace`	Reorder a workspace in the sidebar.

Search & Structure

Tool	Description
`find_window`	Search for a window by content or title.
`tree`	Show the full tree structure (windows/workspaces/panes/surfaces).
`identify`	Show identity info for the current surface/workspace.

Notifications

Tool	Description
`notify`	Send a notification with title, subtitle, and body.
`list_notifications`	List all notifications.
`clear_notifications`	Clear all notifications.

Sidebar Metadata

Tool	Description
`set_status` / `clear_status` / `list_status`	Manage status entries in the sidebar.
`set_progress` / `clear_progress`	Manage a progress bar in the sidebar.
`sidebar_state`	Show the current sidebar state.

Log

Tool	Description
`log`	Write a log entry to the workspace sidebar.
`clear_log`	Clear log entries.
`list_log`	List log entries.

Buffer

Tool	Description
`set_buffer`	Set a named buffer with text content.
`list_buffers`	List all buffers.
`paste_buffer`	Paste a buffer into the terminal.

Terminal Control

Tool	Description
`clear_history`	Clear terminal scrollback history.
`capture_pane`	Capture pane content (tmux-compatible).
`respawn_pane`	Respawn a pane (restart the shell).
`pipe_pane`	Pipe pane output to a shell command.
`display_message`	Display a message overlay.
`trigger_flash`	Trigger a visual flash on the terminal.

Hooks & Misc

Tool	Description
`set_hook`	Set, list, or unset event hooks.
`wait_for`	Wait for or send a named signal.
`set_app_focus`	Set the app focus state.
`markdown_open`	Open a markdown file in a formatted viewer with live reload.
`version`	Show cmux version.
`ping`	Ping the cmux socket.

Browser

Tool	Description
`browser`	Control the cmux built-in browser with subcommands: `open`, `navigate`, `snapshot`, `click`, `type`, `eval`, `screenshot`, and many more.

Real-World Examples

Run tests and analyze failures:

"Run the test suite and tell me which tests are failing"

Claude sends npm test, reads the output, and summarizes the failures.

Multi-tab SSH sessions:

"Open two new tabs, SSH into server-a in one and server-b in the other, then compare their disk usage"

Claude creates tabs, sends SSH commands to each, reads output from both, and compares.

Interactive REPL session:

"Open a Python REPL and check if pandas is installed"

Claude starts python3, types import pandas, reads the result, and reports back.

Long-running process management:

"Start the dev server, wait for it to be ready, then run the health check"

Claude sends the start command, polls the output until "ready" appears, then runs the next command.

Why cmux-mcp?

Background operation

cmux-mcp uses cmux's native CLI (cmux send, cmux read-screen, cmux send-key) which communicates via Unix socket. This means:

Works while cmux is in the background
No window focus stealing
No AppleScript activation delays
Reliable even during app initialization

CLI vs AppleScript

This project was forked from ferrislucas/iterm-mcp and completely rewritten. Here's why:

	AppleScript (iterm-mcp)	cmux CLI (cmux-mcp)
Focus	May steal focus, activate app	No focus change, Unix socket
Buffer reading	Ghostty `write_scrollback_file` (debug-only)	`cmux read-screen` (stable production API)
Startup	Fails if app not fully initialized	Socket-based, more resilient
Targeting	Always "front window"	`--surface` flag for precise pane targeting
Key support	ASCII codes only	Named keys: `ctrl+c`, `escape`, `enter`, arrows
Stability	Fragile to app state changes	Decoupled via socket IPC

Smart completion detection

cmux-mcp doesn't just blindly wait after sending a command. It monitors the TTY's CPU activity to know when a command actually finishes -- even for commands that produce output over time. As of v1.3.1, the polling interval was reduced from 350ms to 150ms and the idle threshold from 1000ms to 500ms, making write_to_terminal roughly 2x faster.

Token efficient

Agents read only the lines they need. A npm test that produces 500 lines of output? The agent first gets told "500 lines were output", then reads just the last 20 lines to check for errors. No wasted context window.

Handling Known cmux Issues

cmux-mcp's architecture avoids several known cmux edge cases:

Issue	Problem	How cmux-mcp handles it
#152	`read-screen` was debug-only	Uses the now-stable production CLI
#2042	Invalid surface ID silently falls back to focused pane	Architecture supports `--surface` for explicit targeting
#1715	TabManager unavailable during startup breaks hooks	Socket-based CLI avoids initialization timing issues
#2153	`send-key` didn't support arrow keys	Uses the updated upstream API with full key support
#2210	Sidebar toggle corrupts prompt via SIGWINCH	Reads buffer after settling delay to avoid corrupted output

Architecture

MCP Client (Claude Code, Claude Desktop, etc.)
    |  stdio
cmux-mcp server
    |  child_process
cmux CLI (send / read-screen / send-key / ...)
    |  Unix socket
cmux.app (Ghostty-based terminal)
    |
macOS PTY

Core modules:

Module	Role
`cmux-path`	Resolves `cmux` binary path: `CMUX_PATH` env > `which cmux` > macOS default paths > fallback
`CommandExecutor`	Sends commands via `cmux send`, waits for completion. Caches TTY path for 60s.
`TtyOutputReader`	Reads terminal buffer via `cmux read-screen`
`SendControlCharacter`	Sends control keys via `cmux send-key`
`ProcessTracker`	Monitors TTY processes for completion detection

Development

npm run build          # Compile TypeScript
npm run watch          # Auto-rebuild on changes
npm test               # Run unit tests
npm run e2e            # Run E2E tests (requires running cmux)
npm run inspector      # Open MCP Inspector for interactive debugging

Safety

No built-in command restrictions. Commands run with your shell's permissions.
Monitor AI activity and interrupt if needed.
Start with focused tasks until you're familiar with the model's behavior.

Credits

Forked from ferrislucas/iterm-mcp
Built for cmux by manaflow.ai

Privacy

cmux-mcp does not collect or transmit any data. All processing is local. See PRIVACY.md for details.

License

MIT