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

Notifications & Sidebar

cmux notify --title "Build Complete" --body "All tests passed"
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-progress 0.75 --label "Running tests"
cmux log --level info --source claude-code "Starting build..."

Terminal I/O Patterns

The core workflow: split a pane, send a command, detect completion, read the output.

Before sending any command, decide how you'll know when it finishes. Claude Code blocks foreground sleep over 2 seconds — pick a completion strategy based on what you're running:

Command type	Example	Strategy
Batch (start→finish)	`npm run build`, `pytest`	`wait-for` signal
Long-running service	`npm run dev`, `docker compose up`	Content poll for "ready" text
Interactive program	`claude`, `node`, `psql`	Content poll for prompt marker
Instant	`echo`, `ls`, `cat`	Immediate `read-screen`

Batch commands → `wait-for`

Chain cmux wait-for -S <signal> to the command. Run the wait with run_in_background: true.

cmux new-split right  # → surface:9
cmux send --surface surface:9 "npm run build && cmux wait-for -S build-done\n"

# run_in_background: true — notified on completion
cmux wait-for build-done --timeout 120 && cmux read-screen --surface surface:9 --scrollback --lines 50

Services / interactive programs → content poll

Poll read-screen for expected text. Use the bundled helper with run_in_background: true:

# run_in_background: true
$SKILL_DIR/scripts/poll-screen.sh surface:9 "ready|listening|Claude Code" --timeout 60

Common match patterns:

Server ready: ready|listening on|started
Claude Code ready: Claude Code|tips:|❯
Task complete: ╭─|❯|\\$\\s*$
Build result: ✓|passed|error|failed

Hybrid example

Server start → wait for ready → then batch work:

cmux send --surface surface:9 "npm run dev\n"
# run_in_background: true — poll for server ready
$SKILL_DIR/scripts/poll-screen.sh surface:9 "ready on" --timeout 30

# (after background notification confirms ready)
cmux send --surface surface:9 "curl localhost:3000/health && cmux wait-for -S health-ok\n"
cmux wait-for health-ok --timeout 10

For detailed patterns (server monitoring, E2E testing, build pipelines, remote Claude Code), read the terminal-io reference.

Sidebar Metadata

# status pill: set-status <key> <value> [--icon name] [--color #hex]
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-status build "Failed" --icon xmark --color "#ff3b30"
cmux clear-status build

# progress bar (0.0 to 1.0, optional --label)
cmux set-progress 0.75 --label "Running tests"
cmux clear-progress

# log messages (leveled, optional --source)
cmux log --level info --source claude-code "Starting build..."
cmux log --level success "Build complete"
cmux log --level warning "3 deprecation warnings"
cmux log --level error "Test suite failed"

Coexistence

In cmux: Use cmux new-split for panes, cmux send/cmux read-screen for terminal I/O, cmux notify for notifications.
Outside cmux: These features are unavailable. Use standard terminal workflows.
Browser automation in cmux: Use the cmux-browser skill for embedded webview automation.
Markdown viewing in cmux: Use cmux markdown open <path> directly to open a live-reloading panel.
With cmux claude-teams: Teams uses its own tmux-shim layer for topology — do not mix direct cmux topology commands with Teams orchestration.

Gotchas

cmux commands fail silently outside cmux — always check $CMUX_WORKSPACE_ID before using any cmux command.
Short refs (surface:7) are session-scoped and may change between sessions — always cmux identify --json at the start of automation to discover current topology.
send includes \n for Enter — cmux send "command\n" sends the command and presses Enter in one call. No need for a separate send-key enter unless you want explicit timing control.
send-keys does not exist — the command is send (text) and send-key (key event). This is different from tmux's send-keys.
press does not exist — to send Ctrl+C, use cmux send-key --surface surface:N ctrl+c.
read-screen returns the current screen state — if a command is still running, the output may be incomplete. Use --scrollback --lines N for history, or use a completion strategy (see Terminal I/O Patterns above).
In Claude Code, sleep over 2 seconds is blocked in foreground — use wait-for for batch commands, content polling for interactive programs. Both require run_in_background: true. Avoid sleep N && read-screen — it reads too early or too late.
Always plan completion detection before sending a command — decide upfront: is this batch (wait-for), service/interactive (content poll), or instant (immediate read)? Sending without a plan leads to blind retries.
set-status --color requires hex values ("#34c759") — named colors like green are not supported.
set-status requires a key (e.g., build) as the first argument — the key allows multiple independent status pills per workspace.
If cmux claude-teams is active, it manages topology through a tmux-compat shim. Direct topology commands (new-split, move-surface) may conflict with Teams orchestration.
Desktop alerts are suppressed when the cmux window is focused and the workspace is active — use cmux log for always-visible status updates.

Deep-Dive References

Reference	When to Use
Terminal I/O	Send commands, read output, server monitoring, E2E testing, build pipelines
Sync and Automation	wait-for synchronization, buffers, cmux.json custom workspace commands
Handles and Identify	Handle syntax, self-identify, caller targeting
Windows and Workspaces	Window/workspace lifecycle and reorder/move
Panes and Surfaces	Splits, surfaces, move/reorder, focus routing
Trigger Flash and Health	Visual flash confirmation and surface health checks
Notifications	Notification CLI, sidebar metadata API, hook patterns