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.

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