{"slug": "cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and", "title": "cmux-orchestrate — a Claude Code skill: drive cmux terminal panes/splits/tabs and the agents running in worker panes via the cmux CLI", "summary": "A developer created cmux-orchestrate, a Claude Code skill that enables driving cmux terminal panes, splits, tabs, and agents via the cmux CLI. The skill provides comprehensive control over terminal layouts, workspaces, windows, and worker panes through commands for targeting, inspecting, and manipulating surfaces.", "body_md": "Captured from `cmux help`\n\n(v0.64.14). The binary is the source of truth — when in doubt run\n`cmux help`\n\n, `cmux <command> --help`\n\n, or `cmux docs <topic>`\n\n. This file is the fast path so you\ndon't have to.\n\n[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)\n\nMost commands accept a target via one of: `--window`\n\n, `--workspace`\n\n, `--pane`\n\n, `--surface`\n\n(`tab-action`\n\nalso takes `--tab`\n\n). Accepted forms:\n\n**short refs**:`window:1`\n\n,`workspace:2`\n\n,`pane:3`\n\n,`surface:4`\n\n,`tab:5`\n\n(default output format)**indexes**: positional integers** UUIDs**: full IDs; request them with the global`--id-format uuids`\n\n(or`both`\n\n)\n\nDefaults when you omit a target: `--surface`\n\n→ `$CMUX_SURFACE_ID`\n\n, `--workspace`\n\n→ `$CMUX_WORKSPACE_ID`\n\n.\nThat means **omitting --surface acts on YOUR pane** — always pass\n\n`--surface`\n\nto touch a worker.Global options go **before** the subcommand: `cmux --json tree`\n\n, `cmux --id-format both list-panes`\n\n.\n\n`cmux --json tree`\n\nreturns:\n\n`caller`\n\n— the surface that ran the command (**you**):`{ pane_ref, surface_ref, tab_ref, workspace_ref, window_ref, surface_type, is_browser_surface }`\n\n`active`\n\n— the truly focused path (same shape)`windows[]`\n\n→ each`{ ref, index, current, selected_workspace_ref, workspaces[] }`\n\n`workspaces[]`\n\n→`{ ref, index, title, selected, panes[] }`\n\n`panes[]`\n\n→`{ ref, index, focused, selected_surface_ref, surface_count, surface_refs[], surfaces[] }`\n\n`surfaces[]`\n\n→`{ ref, index, title, type (terminal|browser), url, tty, focused, selected, here }`\n\n`here:true`\n\nmarks your own surface;`focused/active/selected`\n\nmark the live path. Browser surfaces carry`url`\n\n.\n\n```\ncmux tree [--all] [--workspace <t>] [--window <t>]   # box-drawing; markers ◀ active / ◀ here\ncmux --json tree [--all]                              # structured\ncmux list-windows\ncmux list-workspaces [--window <t>]\ncmux list-panes [--workspace <t>] [--window <t>]\ncmux list-pane-surfaces [--pane <t>] [--workspace <t>]\ncmux list-panels [--workspace <t>]\ncmux current-window | current-workspace\ncmux top [--processes] [--sort cpu|mem|proc] [--flat] [--format tree|tsv]   # per-pane process/resource view\ncmux memory [--all] [--groups <n>]\ncmux identify [--surface <t>] ...                     # what/where is this surface\ncmux capabilities                                     # what this cmux build supports\ncmux new-split <left|right|up|down> [--surface <t>] [--panel <t>] [--focus true|false]\ncmux new-pane [--type terminal|browser] [--direction left|right|up|down] [--url <url>] [--focus ...]\ncmux new-surface [--type terminal|browser] [--pane <t>] [--url <url>]   # new tab inside a pane\ncmux close-surface [--surface <t>]\ncmux move-surface --surface <t> [--pane <t>] [--before|--after <t>] [--index <n>]\ncmux split-off --surface <t> <left|right|up|down>     # pop a surface into its own split\ncmux reorder-surface --surface <t> (--index <n> | --before <t> | --after <t>)\ncmux focus-pane --pane <t>\ncmux focus-panel --panel <t>\ncmux focus-window --window <id>\ncmux refresh-surfaces\n```\n\nBrowser-pane helpers exist too (`cmux browser ...`\n\n, `cmux new-pane --type browser --url ...`\n\n).\n\n```\ncmux new-workspace [--name <title>] [--description <text>] [--cwd <path>] [--command <text>] [--focus ...]\ncmux select-workspace --workspace <t>\ncmux close-workspace --workspace <t>\ncmux move-tab-to-new-workspace [--surface <t>] [--title <text>]\ncmux reorder-workspace --workspace <t> (--index <n> | --before <t> | --after <t>)\ncmux workspace-action --action <name> [--workspace <t>] [--title <text>] [--color <name|#hex>]\ncmux new-window | close-window --window <id> | focus-window --window <id>\ncmux move-workspace-to-window --workspace <t> --window <t>\ncmux rename-tab [--surface <t>] [--tab <t>] <title>\ncmux rename-workspace [--workspace <t>] <title>\ncmux rename-window [--window <t>] <title>\ncmux send [--surface <t>] [--] <text>        # types text; \\n,\\r=Enter  \\t=Tab. Append \\n to submit.\ncmux send-key [--surface <t>] [--] <key>     # one key event: enter, tab, up, down, left, right,\n                                             #   ctrl+c, ctrl+d, esc, \"1\", \"y\", ...\ncmux send-panel --panel <t> <text>           # same but target a panel\ncmux send-key-panel --panel <t> <key>\ncmux read-screen [--surface <t>] [--scrollback] [--lines <n>]   # plain-text screen dump\n```\n\nRead-then-respond is the safe loop for answering an agent's question in a worker (see SKILL.md).\n`read-screen`\n\nis for terminal surfaces; for a browser surface read its `url`\n\n/use `cmux browser`\n\n.\n\n```\ncmux jump-to-unread                          # Cmd+Shift+U equivalent\ncmux list-notifications\ncmux open-notification --id <uuid>\ncmux mark-notification-read (--id <uuid> | --workspace <t> | --all)\ncmux dismiss-notification (--id <uuid> | --all-read)\ncmux clear-notifications [--workspace <t>]\ncmux notify --title <text> [--subtitle <text>] [--body <text>] [--surface <t>]\ncmux trigger-flash [--surface <t>]\n```\n\nUse these to surface Manager state to the human, especially during AFK runs.\n\n```\ncmux set-status <key> <value> [--icon <name>] [--color <#hex>] [--priority <n>]\ncmux clear-status <key>      |  cmux list-status\ncmux set-progress <0.0-1.0> [--label <text>]   |  cmux clear-progress\ncmux log [--level <level>] [--source <name>] <message>   |  cmux list-log [--limit <n>]  |  cmux clear-log\ncmux right-sidebar <toggle|show|hide|focus|files|find|vault|sessions|feed|dock> [--no-focus]\ncmux sidebar <validate|reload|select> [name]\n```\n\nVault = 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.\n\n```\ncmux docs agents            # agent hook integrations, feed approvals, notifications, session restore\ncmux hooks setup [<agent>]  # install cmux hooks for an agent (e.g. so its notifications reach cmux)\ncmux hooks <agent> <install|uninstall|event>\ncmux claude-teams [claude-args...]   # launch Claude in a team layout\ncmux codex-teams  [codex-args...]    # launch Codex in a team layout\ncmux omo|omx|omc [args...]           # opencode / omx / omc launchers\ncmux restore-session | cmux surface resume <set|show|get|clear>\n```\n\n`--json`\n\nand`--id-format`\n\nare**global**— before the subcommand.`cmux send`\n\nwithout a trailing`\\n`\n\nonly types; it won't run/submit.- Omitting\n`--surface`\n\ntargets**your own** pane (`$CMUX_SURFACE_ID`\n\n). Pass`--surface`\n\nfor workers. - Refs/indexes shift as panes open/close — re-run\n`cmux --json tree`\n\nright before acting; use`--id-format uuids`\n\nfor durable IDs across a long run. - Prefer panes over tab groups (easy to lose track of tab groups).\n- Config:\n`~/.config/cmux/cmux.json`\n\nand Ghostty at`~/.config/ghostty/config`\n\n;`cmux reload-config`\n\nreloads both in place. Back up`cmux.json`\n\nto a timestamped`.bak`\n\nbefore editing.\n\nThe workshop's copy-paste Manager prompt (adapt refs/roles to the current workspace):\n\nYou 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.\n\n- Build the layout:\n`cmux new-split right`\n\n,`cmux new-pane`\n\n; name tabs`cmux rename-tab \"<role>\"`\n\n.- Inspect live state before acting:\n`cmux --json tree`\n\n,`cmux list-panes`\n\n.- Delegate then read back:\n`cmux send --surface surface:N -- \"<task>\\n\"`\n\n, then`cmux read-screen --surface surface:N`\n\n.- You talk to me; workers do the work. Report status; don't let workers drift — re-check\n`cmux --json tree`\n\n. Guardrail: prefer panes over tab groups.", "url": "https://wpnews.pro/news/cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and", "canonical_source": "https://gist.github.com/EternallLight/b1b97ba76f33d2937e97a69e645b55f0", "published_at": "2026-06-29 12:22:16+00:00", "updated_at": "2026-07-04 03:18:24.397424+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["cmux", "Claude Code", "cmux-orchestrate"], "alternates": {"html": "https://wpnews.pro/news/cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and", "markdown": "https://wpnews.pro/news/cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and.md", "text": "https://wpnews.pro/news/cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and.txt", "jsonld": "https://wpnews.pro/news/cmux-orchestrate-a-claude-code-skill-drive-cmux-terminal-panes-splits-tabs-and.jsonld"}}