Control cmux terminal workspaces and browser surfaces

Controls cmux, a native macOS terminal app for running multiple AI coding agents in parallel, through its CLI and a Unix-socket JSON-RPC API for full topology and browser control - inspecting, creating, closing, or rearranging panes, surfaces, and workspaces, and sending input to or monitoring agents running inside cmux. Its object model has four levels: a Window is the top-level macOS window, a Workspace is a sidebar tab tied to 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 a workspace or surface number, with UUIDs also accepted as input and available as output via a flag.

Use it when you need to inspect, create, close, or rearrange cmux panes, surfaces, or workspaces, or when you need to send input to or monitor agents running inside cmux. It is macOS-only, with no Linux or Windows port. Getting reference syntax wrong fails silently rather than erroring loudly: always use a prefixed ref like pane:38 or surface:46, since a bare number is treated as an index into a list rather than an actual id, usually pointing at nothing and failing silently. Reading a pane's screen has no direct pane flag at all - read-screen and capture-pane only accept --workspace or --surface, and passing --pane errors while an omitted target quietly falls back to reading your own surface, leading to wrong conclusions drawn from your own footer instead of the pane you meant to inspect; the fix is to resolve the pane to a surface first, then read that surface. Never append a stderr-suppressing redirect to cmux commands, since errors carry the actual ref or flag mistake and suppressing them is the single biggest cause of a mysteriously empty result.

Detecting whether you're inside cmux checks for the Unix socket and the workspace-id environment variable; every cmux-spawned terminal is injected with CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH, and CMUX_PORT, and automation should always anchor to CMUX_WORKSPACE_ID specifically, since the visually focused workspace may not actually be the calling agent's own workspace. Core topology commands identify the caller, dump the full hierarchy, and list workspaces, panes, and surfaces; layout commands create a new workspace or pane, move or reorder a surface between panes, split a surface off, or close it. Sending input has its own naming trap: there is no send-surface or send-key-surface command - a specific surface is targeted by passing --surface to the plain send and send-key commands instead:

cmux send --surface surface:7 "npm run build"               # specific surface (NOT send-surface)
cmux send-key --surface surface:7 enter                     # specific surface (NOT send-key-surface)

send-panel/send-key-panel exist only for panels, never for surfaces. Notifications and sidebar metadata commands can set a toast, a named status with an icon and color, a progress bar, a leveled log line, a focus-drawing flash cue, or dump the sidebar's full metadata state. Browser automation runs over WKWebView through a fixed workflow of open, wait, snapshot, act, re-snapshot, returning interactive elements as short handles to fill or click, plus navigation, inspection, wait-for-selector-or-url, cookie and storage-state session commands, and console, error, and screenshot diagnostics - though WKWebView explicitly does not support viewport emulation, geolocation or offline emulation, trace recording, network route interception, or raw input injection, all returning a not-supported result instead.

The markdown and PDF viewer opens a live-watching right-side pane, but by default spawns a brand-new pane on every call even when a right pane already exists; keeping every doc as a tab in one shared right pane requires finding that pane's existing markdown surface first and opening the new file targeted at that surface id, then moving any stray new surface into the right pane if one still spawned. Swapping the file shown in that single right pane has a strict, order-dependent fix: the previous surface must be closed first, then the new file opened fresh - moving an existing viewer, or opening before closing, both leave the pane blank. Several hard-won lessons cut across all of this: surface refs are global across the whole app, not scoped to one workspace, so a ref from an earlier turn should always be re-verified rather than assumed still valid; moving a markdown viewer with move-surface frequently leaves it rendering blank even though its own health check looks fine, and the only reliable fix is closing it and reopening fresh rather than refreshing it; a markdown surface can never be screenshotted or read as a screen, so verifying it rendered means asking the user or opening the same file in a browser surface instead; and there is no list-surfaces command at all, only list-pane-surfaces. Settings live in a canonical JSON config with an optional project-local override, while terminal rendering itself, meaning font, cursor, theme, and scrollback, lives in a separate Ghostty config file rather than the cmux config - and any edit to the cmux config should be preceded by a timestamped backup copy so the user can revert. Installation goes through Homebrew plus a manual symlink into the local bin path, with hook setup available for all detected agents or a named subset, and native session-resume is supported across a long list of agents including Claude Code, Codex, Grok, OpenCode, Pi, Amp, Cursor CLI, Gemini, and several others. An advanced Unix-socket JSON-RPC v2 API exists for tight loops where subprocess spawn cost actually matters, gated by an access mode that defaults to only cmux-spawned processes, with automation, password, and an explicitly unsafe allow-all mode also available - external processes hitting a connection failure are almost always blocked by that default mode. A short set of non-disruptive-automation rules governs anything that could yank the user's focus: always anchor to the workspace id rather than assuming the focused one is the target, never call a focus-changing command speculatively, build a layout additively in one call rather than create-then-move-then-focus, reuse an existing helper pane before creating a new one, never send input to a surface outside the caller's own workspace without explicit request, and check surface health before routing input into UI state that might be stale.

Agents and developers orchestrating multiple parallel AI coding sessions inside cmux on macOS who need precise, non-disruptive control over panes, surfaces, workspaces, and embedded browser automation, without silently misfiring on cmux's ref-syntax and pane-versus-surface distinctions.