cmux Control

macOS 14.0+. Prefer the CLI; if cmux is not on PATH, use /Applications/cmux.app/Contents/Resources/bin/cmux.

Targeting and safety

Window → workspace → pane → surface: macOS window → sidebar project/branch tab → split region → terminal, browser, or Markdown tab.

• Anchor to the caller's CMUX_WORKSPACE_ID. Never assume the visually focused workspace is the target. Outside cmux, identify the intended workspace before acting.
• Use prefixed refs or UUIDs. workspace:2, pane:1, surface:7; bare numbers are indexes, not IDs. Output defaults to refs; --id-format uuids|both includes UUIDs.
• Refresh targets. Surface refs are global, not workspace-local. Re-list before reusing them; check cmux surface-health before sending input when state may be stale.
• Preserve focus. Pass --focus false wherever supported. Use select-workspace, focus-pane, focus-panel, or focus-surface only on explicit user request.
• Respect ownership. Never send input to surfaces you do not own. Stay in the caller's workspace unless the user explicitly requests cross-workspace routing.
• Reuse one helper pane. Use an existing non-caller helper pane or create one on the right. Create the intended layout directly with new-pane --type … --focus false.
• Keep errors visible. Never append 2>/dev/null; stderr and exit status reveal invalid refs and flags.

Inspect, read, and send

Check connectivity, identify the caller, and resolve the target pane to a surface. Replace example refs with those found in the current output.

cmux ping
cmux identify --json
cmux tree
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-pane-surfaces --workspace "$CMUX_WORKSPACE_ID" --pane pane:1
cmux read-screen --surface surface:7 --lines 100