Control cmux terminal workspaces and browser surfaces

Inspects, creates, closes and rearranges cmux panes, surfaces and workspaces, and sends input to or monitors AI coding agents running inside them. cmux is a native macOS terminal app for running multiple AI coding agents in parallel, exposing both a cmux CLI and a Unix-socket JSON-RPC API at /tmp/cmux.sock for full topology and browser control.

Four core concepts nest inside each other: a Window is a top-level macOS cmux window; a Workspace is a sidebar tab within a window representing one git branch or project context; a Pane is a split region inside a workspace; and a Surface is a tab inside a pane, either terminal or browser. Handles default to short refs like workspace:2, pane:1 or surface:7, with UUIDs also accepted as input and --id-format uuids|both for UUID output.

Ref syntax has sharp edges: refs must always be prefixed (pane:38, not a bare number), since a bare number is treated as an index rather than an ID and usually fails silently against a nonexistent index; read-screen and capture-pane have no --pane flag at all, targeting only --workspace or --surface, so reading a pane requires first resolving it to a surface with cmux list-pane-surfaces --pane pane:N and then cmux read-screen --surface surface:N; and 2>/dev/null should never be appended to cmux commands, since errors go to stderr with exit code 1 and suppressing them blinds the caller to its own ref or flag mistakes, the leading cause of silent "(no output)" failures.

Detecting cmux in a shell checks for the socket at ${CMUX_SOCKET_PATH:-/tmp/cmux.sock} and the presence of CMUX_WORKSPACE_ID; every cmux-spawned terminal injects CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH and CMUX_PORT, and automation should always anchor to CMUX_WORKSPACE_ID rather than assume the visually focused workspace is the caller's own.

Topology commands cover identifying the current window/workspace/pane/surface, dumping the full hierarchy, listing workspaces/panes/surfaces, and creating, moving, splitting, reordering or closing panes and surfaces:

cmux identify --json
cmux tree
cmux new-workspace --name "feature-x" --cwd /path/to/repo
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false

When launching a Pi Agent inside a cmux pane and polling for output, short 2-5 second sleep intervals are recommended over longer ones, since Pi streams tokens quickly on Opus 4.8 Fast via OpenRouter; a longer sleep is reserved for genuinely large builds or refactors. After every agent check, a one-line concise status update should go to the user on what the agent is doing and whether it's on track; a Claude Code session's prefilled predicted next message after finishing is Claude's own draft, not the user speaking.

Sending input has no send-surface/send-key-surface commands; a specific surface is targeted with the --surface flag on the ordinary send/send-key commands, while send-panel/send-key-panel exist only for panels. Notifications and sidebar metadata are set through notify, set-status, set-progress, log (with info/progress/success/warning/error levels), trigger-flash for a blue-ring attention cue, and sidebar-state --json to dump all metadata.

Browser automation runs on WKWebView through an open, wait, snapshot, act, re-snapshot workflow: opening a URL returns a surface ref used for waiting on load state, taking an interactive snapshot that returns addressable elements, filling or clicking them, navigating, reading page state, evaluating JavaScript, waiting on a selector or URL substring, managing cookies and saved session state, and diagnostics like console/error listing and screenshots. WKWebView does not support viewport emulation, geolocation or offline emulation, trace recording, network route interception, or raw input injection, all returning not_supported.

The markdown viewer opens a live-watching renderer for a file, or auto-routes a PDF to a right-side viewer; it accepts --workspace, --surface, --window, --direction and --focus but has no --pane flag, so targeting a specific pane means passing an existing markdown surface already in that pane. Since markdown open creates a new pane by default even with --direction right, keeping all docs as tabs in one right pane requires finding that pane's existing surfaces first and opening against one of them, then moving any stray new surface into place if one still spawned. Swapping the file shown in a single right markdown pane must close the previous surface first and only then open the new file fresh; opening before closing, or moving an existing viewer, leaves the pane blank.

Several hard-won lessons are called out: surface refs are global rather than per-workspace, so a ref from an earlier command may live in a different window, and panes/surfaces should always be re-listed before reusing a ref; moving a markdown viewer often leaves it rendering blank even though it still reports healthy, and the fix is closing and reopening fresh rather than retrying a refresh; a markdown surface cannot be screenshotted or read via read-screen since it isn't a terminal and WKWebView-only screenshot doesn't apply, so verifying render requires asking the user or opening it in a browser surface instead; and cmux list-surfaces does not exist, only cmux list-pane-surfaces.

Settings live in ~/.config/cmux/cmux.json (with project-local overrides at .cmux/cmux.json or ./cmux.json), while terminal rendering (font, cursor, theme, scrollback, opacity, blur) lives separately in ~/.config/ghostty/config; cmux docs settings should be read before editing, and cmux.json should be copied to a timestamped .bak before any edit so the user can revert. Installation and hooks:

brew tap manaflow-ai/cmux && brew install --cask cmux
sudo ln -sf /Applications/cmux.app/Contents/Resources/bin/cmux /usr/local/bin/cmux
cmux hooks setup

Native session-resume is supported for Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory and Qoder.

The Unix-socket JSON-RPC v2 API at /tmp/cmux.sock is for tight loops where subprocess spawn cost matters, with method prefixes system.*, window.*, workspace.*, pane.*, surface.*, notification.* and browser.*, documented fully with a Python client example in references/socket-api.md; access modes are cmuxOnly (default, cmux-spawned processes only), automation, password, and an unsafe allowAll.

Six non-disruptive automation rules prevent yanking the user's focus: always anchor to CMUX_WORKSPACE_ID; never call a focus-changing verb (select-workspace, focus-pane, focus-panel, focus-surface) speculatively, only on explicit user request, passing --focus false elsewhere; build layout additively in one call rather than a create-then-move-then-focus chain; reuse an existing right-side helper pane rather than creating a new one when possible; never send input to a surface outside the caller's own workspace unless explicitly asked; and check surface health before routing input when UI state may be stale. Known pitfalls include socket connection failures from processes outside the default cmuxOnly mode, macOS-only support with no Linux or Windows port, WKWebView's lack of CDP-equivalent network mocking, resume stripping sensitive environment variables that need re-injecting, skill files snapshotting at app start so edits require a restart, and legacy v1 socket payloads being rejected in favor of v2 JSON-RPC only.

Use it to inspect, create, close or rearrange cmux panes, surfaces or workspaces, or to send input to or monitor AI agents running inside cmux. Skip focus-changing commands unless the user explicitly asked, and skip sending input to a surface outside the caller's own workspace without explicit cross-workspace routing instructions.

Input is a cmux ref (workspace, pane, or surface) plus the desired action, terminal input, browser command, or metadata update. Output is the requested topology state, a completed input send, a browser automation result, or a status/notification update in the cmux UI.

Controls the native macOS cmux app via its cmux CLI and its /tmp/cmux.sock JSON-RPC v2 socket API; supports native session-resume for Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, Antigravity, Rovo Dev, Hermes, Copilot, CodeBuddy, Factory and Qoder.

Agents and developers running multiple AI coding agents in parallel on macOS who need to control cmux's panes, workspaces, browser automation, and agent input programmatically.