# cmux-orchestrate — a Claude Code skill: drive cmux terminal panes/splits/tabs and the agents running in worker panes via the cmux CLI > Source: > Published: 2026-06-29 12:22:16+00:00 Captured from `cmux help` (v0.64.14). The binary is the source of truth — when in doubt run `cmux help` , `cmux --help` , or `cmux docs ` . This file is the fast path so you don't have to. [Targeting model (refs, indexes, UUIDs)](https://gist.github.com/starred.atom#targeting-model)[JSON tree shape](https://gist.github.com/starred.atom#json-tree-shape)[Inspect](https://gist.github.com/starred.atom#inspect)[Layout: panes / splits / surfaces](https://gist.github.com/starred.atom#layout)[Workspaces & windows](https://gist.github.com/starred.atom#workspaces--windows)[Naming](https://gist.github.com/starred.atom#naming)[Send / read / keys](https://gist.github.com/starred.atom#send--read--keys)[Notifications & unread](https://gist.github.com/starred.atom#notifications--unread)[Status, progress, log](https://gist.github.com/starred.atom#status-progress-log)[Sidebar (Files / Find / Vault)](https://gist.github.com/starred.atom#sidebar)[Agents, hooks, teams](https://gist.github.com/starred.atom#agents-hooks-teams)[Gotchas](https://gist.github.com/starred.atom#gotchas)[Manager prompt (workshop copy-paste)](https://gist.github.com/starred.atom#manager-prompt) Most commands accept a target via one of: `--window` , `--workspace` , `--pane` , `--surface` (`tab-action` also takes `--tab` ). Accepted forms: **short refs**:`window:1` ,`workspace:2` ,`pane:3` ,`surface:4` ,`tab:5` (default output format)**indexes**: positional integers** UUIDs**: full IDs; request them with the global`--id-format uuids` (or`both` ) Defaults when you omit a target: `--surface` → `$CMUX_SURFACE_ID` , `--workspace` → `$CMUX_WORKSPACE_ID` . That means **omitting --surface acts on YOUR pane** — always pass `--surface` to touch a worker.Global options go **before** the subcommand: `cmux --json tree` , `cmux --id-format both list-panes` . `cmux --json tree` returns: `caller` — the surface that ran the command (**you**):`{ pane_ref, surface_ref, tab_ref, workspace_ref, window_ref, surface_type, is_browser_surface }` `active` — the truly focused path (same shape)`windows[]` → each`{ ref, index, current, selected_workspace_ref, workspaces[] }` `workspaces[]` →`{ ref, index, title, selected, panes[] }` `panes[]` →`{ ref, index, focused, selected_surface_ref, surface_count, surface_refs[], surfaces[] }` `surfaces[]` →`{ ref, index, title, type (terminal|browser), url, tty, focused, selected, here }` `here:true` marks your own surface;`focused/active/selected` mark the live path. Browser surfaces carry`url` . ``` cmux tree [--all] [--workspace ] [--window ] # box-drawing; markers ◀ active / ◀ here cmux --json tree [--all] # structured cmux list-windows cmux list-workspaces [--window ] cmux list-panes [--workspace ] [--window ] cmux list-pane-surfaces [--pane ] [--workspace ] cmux list-panels [--workspace ] cmux current-window | current-workspace cmux top [--processes] [--sort cpu|mem|proc] [--flat] [--format tree|tsv] # per-pane process/resource view cmux memory [--all] [--groups ] cmux identify [--surface ] ... # what/where is this surface cmux capabilities # what this cmux build supports cmux new-split [--surface ] [--panel ] [--focus true|false] cmux new-pane [--type terminal|browser] [--direction left|right|up|down] [--url ] [--focus ...] cmux new-surface [--type terminal|browser] [--pane ] [--url ] # new tab inside a pane cmux close-surface [--surface ] cmux move-surface --surface [--pane ] [--before|--after ] [--index ] cmux split-off --surface # pop a surface into its own split cmux reorder-surface --surface (--index | --before | --after ) cmux focus-pane --pane cmux focus-panel --panel cmux focus-window --window cmux refresh-surfaces ``` Browser-pane helpers exist too (`cmux browser ...` , `cmux new-pane --type browser --url ...` ). ``` cmux new-workspace [--name ] [--description <text>] [--cwd <path>] [--command <text>] [--focus ...] cmux select-workspace --workspace <t> cmux close-workspace --workspace <t> cmux move-tab-to-new-workspace [--surface <t>] [--title <text>] cmux reorder-workspace --workspace <t> (--index <n> | --before <t> | --after <t>) cmux workspace-action --action <name> [--workspace <t>] [--title <text>] [--color <name|#hex>] cmux new-window | close-window --window <id> | focus-window --window <id> cmux move-workspace-to-window --workspace <t> --window <t> cmux rename-tab [--surface <t>] [--tab <t>] <title> cmux rename-workspace [--workspace <t>] <title> cmux rename-window [--window <t>] <title> cmux send [--surface <t>] [--] <text> # types text; \n,\r=Enter \t=Tab. Append \n to submit. cmux send-key [--surface <t>] [--] <key> # one key event: enter, tab, up, down, left, right, # ctrl+c, ctrl+d, esc, "1", "y", ... cmux send-panel --panel <t> <text> # same but target a panel cmux send-key-panel --panel <t> <key> cmux read-screen [--surface <t>] [--scrollback] [--lines <n>] # plain-text screen dump ``` Read-then-respond is the safe loop for answering an agent's question in a worker (see SKILL.md). `read-screen` is for terminal surfaces; for a browser surface read its `url` /use `cmux browser` . ``` cmux jump-to-unread # Cmd+Shift+U equivalent cmux list-notifications cmux open-notification --id <uuid> cmux mark-notification-read (--id <uuid> | --workspace <t> | --all) cmux dismiss-notification (--id <uuid> | --all-read) cmux clear-notifications [--workspace <t>] cmux notify --title <text> [--subtitle <text>] [--body <text>] [--surface <t>] cmux trigger-flash [--surface <t>] ``` Use these to surface Manager state to the human, especially during AFK runs. ``` cmux set-status <key> <value> [--icon <name>] [--color <#hex>] [--priority <n>] cmux clear-status <key> | cmux list-status cmux set-progress <0.0-1.0> [--label <text>] | cmux clear-progress cmux log [--level <level>] [--source <name>] <message> | cmux list-log [--limit <n>] | cmux clear-log cmux right-sidebar <toggle|show|hide|focus|files|find|vault|sessions|feed|dock> [--no-focus] cmux sidebar <validate|reload|select> [name] ``` Vault = past conversations you can resume in a new tab (workshop noted search is still rough). In the GUI: Cmd+Alt+B opens the right sidebar; 1/2/3 switch Files/Find/Vault. ``` cmux docs agents # agent hook integrations, feed approvals, notifications, session restore cmux hooks setup [<agent>] # install cmux hooks for an agent (e.g. so its notifications reach cmux) cmux hooks <agent> <install|uninstall|event> cmux claude-teams [claude-args...] # launch Claude in a team layout cmux codex-teams [codex-args...] # launch Codex in a team layout cmux omo|omx|omc [args...] # opencode / omx / omc launchers cmux restore-session | cmux surface resume <set|show|get|clear> ``` `--json` and`--id-format` are**global**— before the subcommand.`cmux send` without a trailing`\n` only types; it won't run/submit.- Omitting `--surface` targets**your own** pane (`$CMUX_SURFACE_ID` ). Pass`--surface` for workers. - Refs/indexes shift as panes open/close — re-run `cmux --json tree` right before acting; use`--id-format uuids` for durable IDs across a long run. - Prefer panes over tab groups (easy to lose track of tab groups). - Config: `~/.config/cmux/cmux.json` and Ghostty at`~/.config/ghostty/config` ;`cmux reload-config` reloads both in place. Back up`cmux.json` to a timestamped`.bak` before editing. The workshop's copy-paste Manager prompt (adapt refs/roles to the current workspace): You are the Manager agent running in my focused cmux pane. I will only talk to you; you coordinate worker panes. Use the REAL cmux CLI (do not invent flags). Keep upfront planning human-led — confirm the plan with me before delegating. - Build the layout: `cmux new-split right` ,`cmux new-pane` ; name tabs`cmux rename-tab "<role>"` .- Inspect live state before acting: `cmux --json tree` ,`cmux list-panes` .- Delegate then read back: `cmux send --surface surface:N -- "<task>\n"` , then`cmux read-screen --surface surface:N` .- You talk to me; workers do the work. Report status; don't let workers drift — re-check `cmux --json tree` . Guardrail: prefer panes over tab groups.