claw-mux

cmux Core Control

Use this skill to control cmux topology, terminal I/O (send commands to other panes and read output), notifications, and sidebar metadata.

Environment Detection

cmux sets $CMUX_WORKSPACE_ID and $CMUX_SURFACE_ID in every terminal it spawns. Check before using cmux commands:

if [ -z "$CMUX_WORKSPACE_ID" ]; then
  echo "Not running inside cmux — cmux commands unavailable"
fi

If not in cmux, fall back to standard tools (no pane splitting, no cmux notifications).

Core Concepts

• Window: Top-level macOS cmux window.
• Workspace: Tab-like group within a window (sidebar entry).
• Pane: Split container in a workspace.
• Surface: A tab within a pane (terminal or browser panel).

Hierarchy: Window > Workspace > Pane > Surface

Default output uses short refs: window:N, workspace:N, pane:N, surface:N. UUIDs are still accepted as inputs. Request UUID output only when needed: --id-format uuids|both.

Fast Start

Topology

# Always identify first — short refs (pane:1, surface:N) are session-scoped
cmux identify --json                                          # current caller context
cmux list-workspaces                                          # list workspaces
cmux list-panes                                               # list panes in workspace
cmux list-pane-surfaces --pane pane:1                          # list surfaces in pane
cmux new-workspace                                            # create workspace
cmux new-split right                                           # split current surface to the right
cmux move-surface --surface surface:7 --pane pane:2            # move surface between panes
cmux trigger-flash --surface surface:7                         # visual flash

Terminal I/O (send commands to other panes, read output)

cmux send --surface surface:N "echo hello\n"                   # send text + Enter (\n = Enter)
cmux send --surface surface:N "npm start\n"                    # run a command in another pane
cmux send-key --surface surface:N enter                        # send Enter key separately
cmux send-key --surface surface:N ctrl+c                       # send Ctrl+C (stop a process)
cmux read-screen --surface surface:N                           # read visible terminal text
cmux read-screen --surface surface:N --scrollback              # include scrollback history
cmux read-screen --surface surface:N --scrollback --lines 200  # last 200 lines only