{
  "markdown": "# cmux-mcp\n\n[한국어](./README.ko.md)\n\n**MCP server that gives AI agents full control of your [cmux](https://github.com/manaflow-ai/cmux) terminal.**\n\nLet 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.\n\n## Quick Start\n\n### Option A: Claude Code Plugin (Recommended)\n\n```\n/plugin marketplace add daegweon/cmux-mcp\n/plugin install cmux-mcp@cmux-tools\n```\n\nThat's it. The MCP server is configured automatically.\n\n### Option B: npx (No build required)\n\nEdit `~/.claude/settings.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"cmux-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cmux-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Code.\n\n### Option C: Clone and build\n\n```bash\ngit clone https://github.com/daegweon/cmux-mcp.git\ncd cmux-mcp\nnpm install && npm run build\n```\n\nEdit `~/.claude/settings.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"cmux-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/cmux-mcp/build/index.js\"]\n    }\n  }\n}\n```\n\nRestart Claude Code.\n\n<details>\n<summary>Claude Desktop setup</summary>\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"cmux-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/cmux-mcp/build/index.js\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n</details>\n\n<details>\n<summary>Any MCP client</summary>\n\ncmux-mcp communicates over stdio. Point your MCP client to `node /path/to/cmux-mcp/build/index.js`.\n\n</details>\n\n### Requirements\n\n- macOS\n- [cmux.app](https://github.com/manaflow-ai/cmux) installed and running\n- Node.js 18+\n- cmux socket control mode set to **Automation** or **Open Access** (Settings > Automation > Socket Control Mode)\n\n## Tools\n\ncmux-mcp exposes the full cmux CLI as MCP tools. All terminal I/O tools support an optional `surface` parameter for targeting specific tabs.\n\n### Terminal I/O\n\n| Tool | Description |\n|------|-------------|\n| `write_to_terminal` | Send commands to the terminal. Enter is appended automatically. Returns new output line count. |\n| `read_terminal_output` | Read the last N lines from the terminal buffer. |\n| `send_control_character` | Send Ctrl+C, Ctrl+Z, Escape, or any control character. |\n\n### Surface (Tab) Management\n\n| Tool | Description |\n|------|-------------|\n| `list_surfaces` | List all tabs in a workspace with IDs and titles. |\n| `new_surface` | Create a new terminal tab. |\n| `close_surface` | Close a specific tab. |\n| `focus_surface` | Focus (activate) a specific tab. |\n| `move_surface` | Move a tab to a different pane, window, or position. |\n| `reorder_surface` | Reorder a tab within its pane. |\n| `rename_tab` | Rename a tab. |\n| `new_split` | Split the current surface into a new pane. |\n| `drag_surface_to_split` | Drag a surface to create a split. |\n| `refresh_surfaces` | Refresh all surfaces. |\n| `surface_health` | Check health of surfaces. |\n\n### Pane Management\n\n| Tool | Description |\n|------|-------------|\n| `list_panes` | List all panes in a workspace. |\n| `new_pane` | Create a new pane (split) with direction. |\n| `focus_pane` | Focus a specific pane. |\n| `resize_pane` | Resize a pane in a given direction. |\n| `swap_pane` | Swap two panes. |\n| `break_pane` | Break a pane out into a new workspace. |\n| `join_pane` | Join a pane into another pane. |\n| `last_pane` | Switch to the last active pane. |\n| `list_panels` | List all panels in a workspace. |\n| `focus_panel` | Focus a specific panel. |\n\n### Window Management\n\n| Tool | Description |\n|------|-------------|\n| `list_windows` | List all windows. |\n| `new_window` | Create a new window. |\n| `close_window` | Close a specific window. |\n| `focus_window` | Focus a specific window. |\n| `current_window` | Show current window info. |\n| `rename_window` | Rename the current window. |\n| `next_window` / `previous_window` / `last_window` | Navigate between windows. |\n| `move_workspace_to_window` | Move a workspace to a different window. |\n\n### Workspace Management\n\n| Tool | Description |\n|------|-------------|\n| `list_workspaces` | List all workspaces. |\n| `new_workspace` | Create a new workspace with optional cwd/command. |\n| `close_workspace` | Close a specific workspace. |\n| `select_workspace` | Switch to a specific workspace. |\n| `rename_workspace` | Rename a workspace. |\n| `current_workspace` | Show current workspace info. |\n| `reorder_workspace` | Reorder a workspace in the sidebar. |\n\n### Search & Structure\n\n| Tool | Description |\n|------|-------------|\n| `find_window` | Search for a window by content or title. |\n| `tree` | Show the full tree structure (windows/workspaces/panes/surfaces). |\n| `identify` | Show identity info for the current surface/workspace. |\n\n### Notifications\n\n| Tool | Description |\n|------|-------------|\n| `notify` | Send a notification with title, subtitle, and body. |\n| `list_notifications` | List all notifications. |\n| `clear_notifications` | Clear all notifications. |\n\n### Sidebar Metadata\n\n| Tool | Description |\n|------|-------------|\n| `set_status` / `clear_status` / `list_status` | Manage status entries in the sidebar. |\n| `set_progress` / `clear_progress` | Manage a progress bar in the sidebar. |\n| `sidebar_state` | Show the current sidebar state. |\n\n### Log\n\n| Tool | Description |\n|------|-------------|\n| `log` | Write a log entry to the workspace sidebar. |\n| `clear_log` | Clear log entries. |\n| `list_log` | List log entries. |\n\n### Buffer\n\n| Tool | Description |\n|------|-------------|\n| `set_buffer` | Set a named buffer with text content. |\n| `list_buffers` | List all buffers. |\n| `paste_buffer` | Paste a buffer into the terminal. |\n\n### Terminal Control\n\n| Tool | Description |\n|------|-------------|\n| `clear_history` | Clear terminal scrollback history. |\n| `capture_pane` | Capture pane content (tmux-compatible). |\n| `respawn_pane` | Respawn a pane (restart the shell). |\n| `pipe_pane` | Pipe pane output to a shell command. |\n| `display_message` | Display a message overlay. |\n| `trigger_flash` | Trigger a visual flash on the terminal. |\n\n### Hooks & Misc\n\n| Tool | Description |\n|------|-------------|\n| `set_hook` | Set, list, or unset event hooks. |\n| `wait_for` | Wait for or send a named signal. |\n| `set_app_focus` | Set the app focus state. |\n| `markdown_open` | Open a markdown file in a formatted viewer with live reload. |\n| `version` | Show cmux version. |\n| `ping` | Ping the cmux socket. |\n\n### Browser\n\n| Tool | Description |\n|------|-------------|\n| `browser` | Control the cmux built-in browser with subcommands: `open`, `navigate`, `snapshot`, `click`, `type`, `eval`, `screenshot`, and [many more](https://github.com/manaflow-ai/cmux). |\n\n### Real-World Examples\n\n**Run tests and analyze failures:**\n> \"Run the test suite and tell me which tests are failing\"\n\nClaude sends `npm test`, reads the output, and summarizes the failures.\n\n**Multi-tab SSH sessions:**\n> \"Open two new tabs, SSH into server-a in one and server-b in the other, then compare their disk usage\"\n\nClaude creates tabs, sends SSH commands to each, reads output from both, and compares.\n\n**Interactive REPL session:**\n> \"Open a Python REPL and check if pandas is installed\"\n\nClaude starts `python3`, types `import pandas`, reads the result, and reports back.\n\n**Long-running process management:**\n> \"Start the dev server, wait for it to be ready, then run the health check\"\n\nClaude sends the start command, polls the output until \"ready\" appears, then runs the next command.\n\n## Why cmux-mcp?\n\n### Background operation\n\ncmux-mcp uses cmux's native CLI (`cmux send`, `cmux read-screen`, `cmux send-key`) which communicates via Unix socket. This means:\n\n- Works while cmux is in the background\n- No window focus stealing\n- No AppleScript activation delays\n- Reliable even during app initialization\n\n### CLI vs AppleScript\n\nThis project was forked from [ferrislucas/iterm-mcp](https://github.com/ferrislucas/iterm-mcp) and completely rewritten. Here's why:\n\n| | AppleScript (iterm-mcp) | cmux CLI (cmux-mcp) |\n|---|---|---|\n| **Focus** | May steal focus, activate app | No focus change, Unix socket |\n| **Buffer reading** | Ghostty `write_scrollback_file` (debug-only) | `cmux read-screen` (stable production API) |\n| **Startup** | Fails if app not fully initialized | Socket-based, more resilient |\n| **Targeting** | Always \"front window\" | `--surface` flag for precise pane targeting |\n| **Key support** | ASCII codes only | Named keys: `ctrl+c`, `escape`, `enter`, arrows |\n| **Stability** | Fragile to app state changes | Decoupled via socket IPC |\n\n### Smart completion detection\n\ncmux-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.\n\n### Token efficient\n\nAgents 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.\n\n## Handling Known cmux Issues\n\ncmux-mcp's architecture avoids several known cmux edge cases:\n\n| Issue | Problem | How cmux-mcp handles it |\n|-------|---------|------------------------|\n| [#152](https://github.com/manaflow-ai/cmux/issues/152) | `read-screen` was debug-only | Uses the now-stable production CLI |\n| [#2042](https://github.com/manaflow-ai/cmux/issues/2042) | Invalid surface ID silently falls back to focused pane | Architecture supports `--surface` for explicit targeting |\n| [#1715](https://github.com/manaflow-ai/cmux/issues/1715) | TabManager unavailable during startup breaks hooks | Socket-based CLI avoids initialization timing issues |\n| [#2153](https://github.com/manaflow-ai/cmux/issues/2153) | `send-key` didn't support arrow keys | Uses the updated upstream API with full key support |\n| [#2210](https://github.com/manaflow-ai/cmux/issues/2210) | Sidebar toggle corrupts prompt via SIGWINCH | Reads buffer after settling delay to avoid corrupted output |\n\n## Architecture\n\n```\nMCP Client (Claude Code, Claude Desktop, etc.)\n    |  stdio\ncmux-mcp server\n    |  child_process\ncmux CLI (send / read-screen / send-key / ...)\n    |  Unix socket\ncmux.app (Ghostty-based terminal)\n    |\nmacOS PTY\n```\n\n**Core modules:**\n\n| Module | Role |\n|--------|------|\n| `cmux-path` | Resolves `cmux` binary path: `CMUX_PATH` env > `which cmux` > macOS default paths > fallback |\n| `CommandExecutor` | Sends commands via `cmux send`, waits for completion. Caches TTY path for 60s. |\n| `TtyOutputReader` | Reads terminal buffer via `cmux read-screen` |\n| `SendControlCharacter` | Sends control keys via `cmux send-key` |\n| `ProcessTracker` | Monitors TTY processes for completion detection |\n\n## Development\n\n```bash\nnpm run build          # Compile TypeScript\nnpm run watch          # Auto-rebuild on changes\nnpm test               # Run unit tests\nnpm run e2e            # Run E2E tests (requires running cmux)\nnpm run inspector      # Open MCP Inspector for interactive debugging\n```\n\n## Safety\n\n- No built-in command restrictions. Commands run with your shell's permissions.\n- Monitor AI activity and interrupt if needed.\n- Start with focused tasks until you're familiar with the model's behavior.\n\n## Credits\n\n- Forked from [ferrislucas/iterm-mcp](https://github.com/ferrislucas/iterm-mcp)\n- Built for [cmux](https://github.com/manaflow-ai/cmux) by manaflow.ai\n\n## Privacy\n\ncmux-mcp does not collect or transmit any data. All processing is local. See [PRIVACY.md](./PRIVACY.md) for details.\n\n## License\n\nMIT\n",
  "bytes": 11778,
  "sha": "2f5082e67c51853b0a6913873800d4ae50e8645d341c0a6fb17eeab209710ed1",
  "repo_slug": "daegweon/cmux-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_daegweon_cmux_mcp_cmux_mcp_e3e6611c/readme"
}