cmux-orchestrate — a Claude Code skill: drive cmux terminal panes/splits/tabs and the agents running in worker panes via the cmux CLI

cmux-cli.md

cmux CLI reference

Captured from cmux help (v0.64.14). The binary is the source of truth — when in doubt run cmux help, cmux <command> --help, or cmux docs <topic>. This file is the fast path so you don't have to.

Table of contents

• Targeting model (refs, indexes, UUIDs)
• JSON tree shape
• Inspect
• Layout: panes / splits / surfaces
• Workspaces & windows
• Naming
• Send / read / keys
• Notifications & unread
• Status, progress, log
• Sidebar (Files / Find / Vault)
• Agents, hooks, teams
• Gotchas
• Manager prompt (workshop copy-paste)

Targeting model

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.

JSON tree shape

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.

Inspect

cmux tree [--all] [--workspace <t>] [--window <t>]   # box-drawing; markers ◀ active / ◀ here
cmux --json tree [--all]                              # structured
cmux list-windows
cmux list-workspaces [--window <t>]
cmux list-panes [--workspace <t>] [--window <t>]
cmux list-pane-surfaces [--pane <t>] [--workspace <t>]
cmux list-panels [--workspace <t>]
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 <n>]
cmux identify [--surface <t>] ...                     # what/where is this surface
cmux capabilities                                     # what this cmux build supports

Layout

cmux new-split <left|right|up|down> [--surface <t>] [--panel <t>] [--focus true|false]
cmux new-pane [--type terminal|browser] [--direction left|right|up|down] [--url <url>] [--focus ...]
cmux new-surface [--type terminal|browser] [--pane <t>] [--url <url>]   # new tab inside a pane
cmux close-surface [--surface <t>]
cmux move-surface --surface <t> [--pane <t>] [--before|--after <t>] [--index <n>]
cmux split-off --surface <t> <left|right|up|down>     # pop a surface into its own split
cmux reorder-surface --surface <t> (--index <n> | --before <t> | --after <t>)
cmux focus-pane --pane <t>
cmux focus-panel --panel <t>
cmux focus-window --window <id>
cmux refresh-surfaces

Browser-pane helpers exist too (cmux browser ..., cmux new-pane --type browser --url ...).

Workspaces & windows

cmux new-workspace [--name <title>] [--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>

Naming

cmux rename-tab [--surface <t>] [--tab <t>] <title>
cmux rename-workspace [--workspace <t>] <title>
cmux rename-window [--window <t>] <title>

Send / read / keys

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.

Notifications & unread

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>]

Status, progress, log

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

Sidebar

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.

Agents, hooks, teams

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>

Gotchas

• --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.

Manager prompt

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.

1. Build the layout: cmux new-split right, cmux new-pane; name tabs cmux rename-tab "<role>".
2. Inspect live state before acting: cmux --json tree, cmux list-panes.
3. Delegate then read back: cmux send --surface surface:N -- "<task>\n", then cmux read-screen --surface surface:N.
4. 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.

SKILL.md

name	cmux-orchestrate
description	Use when orchestrating cmux terminal panes, splits, tabs, worker sessions, or agents in other cmux panes, including reading screens, sending commands, answering prompts, jumping to unread activity, or setting AFK check-ins. Do not use for tmux, IDE/browser tabs, deployment replicas, or plain command execution.

cmux Orchestrate

Drive a cmux terminal workspace — build pane layouts, name tabs, send work to worker panes, read their screens, and answer the agents running inside them — translating the user's plain English into real cmux CLI calls fast, without paging through help every time.

cmux is agent-first: it exposes a Unix-socket CLI so an agent can inspect and control the whole window/workspace/pane/surface tree. You don't memorize a GUI; you read the surface and act on it.

Use this whenever the user is controlling cmux panes, splits, tabs, or worker sessions: opening a pane to the right/left/up/down, splitting the terminal, spinning up worker panes, building a manager/worker layout, naming tabs, reading or summarizing another pane, sending commands into another pane, answering Claude or Codex running in another pane, jumping to unread activity, or setting up an AFK check-in loop.

Trigger eagerly even when the user does not say "cmux" but is clearly orchestrating terminal panes: "open a pane", "split the terminal", "the agent in my other tab", "my worker panes", "check the other pane", "send X to the left pane", or "jump to whatever needs input".

0. Gate: are we even in cmux?

Before running any cmux command, confirm the environment:

[ -n "$CMUX_SURFACE_ID" ] && echo "in cmux: surface $CMUX_SURFACE_ID" || echo "NOT in cmux"

If $CMUX_SURFACE_ID is empty, you are not in a cmux workspace. Tell the user, and do not run cmux orchestration commands. (cmux may still launch a new workspace via cmux <path>, but pane/surface control assumes you're inside one.)

$CMUX_SURFACE_ID is this pane (where you're running). That's how you tell yourself apart from workers.

Golden rules

1. Don't invent flags. The cheat sheet below is verified. For anything else, check cmux <command> --help or references/cmux-cli.md. The CLI is the source of truth; your memory of it may be stale.
2. --json is a global flag — it goes BEFORE the subcommand: cmux --json tree, not cmux tree --json.
3. Re-inspect before you act on a worker. Refs like surface:21 / pane:19 and indexes can shift as panes open/close. Run cmux --json tree (or cmux list-panes) to get current refs right before targeting one. Need durable IDs? add --id-format uuids.
4. cmux send only TYPES text. To make a worker actually run a command or submit a prompt, end the text with \n (Enter). \n/\r → Enter, \t → Tab.
5. Prefer panes over tab groups — tab groups are easy to lose track of (workshop guardrail).
6. Keep upfront planning human-led. Confirm the layout/plan with the user before fanning out workers.

Cheat sheet (the basics — no cmux help needed)

Inspect live state (do this first, always):

cmux --json tree        # full window/workspace/pane/surface tree as JSON
cmux tree               # same, human box-drawing view: ◀ active, ◀ here(=you)
cmux list-panes         # enumerate panes
cmux list-pane-surfaces # surfaces (tabs) within panes

In the JSON: caller = you, active = the focused pane/surface, each node has a ref (pane:N/surface:N), focused/selected flags, and titles.

Build the layout:

cmux new-split right                 # split current pane (left|right|up|down)
cmux new-pane                        # new pane; --direction left|right|up|down
cmux new-pane --type browser --url https://example.com   # browser pane
cmux new-surface                     # new surface (tab) inside a pane
cmux new-workspace --name "build"    # whole new workspace

Name things so workers stay findable:

cmux rename-tab "manager"
cmux rename-tab --surface surface:2 "worker-tests"
cmux rename-workspace "feature-x"

Target a specific worker — every action takes --surface surface:N (or --pane, --workspace, --window). Default target is your own surface ($CMUX_SURFACE_ID), so you MUST pass --surface to act on someone else.

Send work into a worker, then read it back:

cmux send --surface surface:2 -- "ls -la\n"          # run a command (note \n)
cmux send --surface surface:2 -- "Investigate the failing auth test and report back\n"  # prompt an agent
cmux read-screen --surface surface:2                 # read its visible screen
cmux read-screen --surface surface:2 --scrollback --lines 200   # deeper history

Use -- before free text so leading dashes/special chars aren't parsed as flags.

Answer the agent running in a worker pane (the key cross-pane move):

cmux read-screen --surface surface:2          # 1. SEE the question first
cmux send --surface surface:2 -- "yes, use option B\n"   # 2a. free-text chat answer
cmux send-key --surface surface:2 enter       # 2b. TUI menu: confirm
cmux send-key --surface surface:2 -- "2"      # 2c. pick numbered option
cmux send-key --surface surface:2 down        # navigate (up|down|enter|tab|ctrl+c …)

See Answering agents in workers below for Claude Code vs Codex prompt styles.

Notifications / jump to what needs you:

cmux jump-to-unread          # = Cmd+Shift+U: jump to a pane with unread activity
cmux list-notifications
cmux focus-pane --pane pane:3

Surface your own status to the human (optional, nice for AFK runs):

cmux set-status state "checking workers" --icon eye
cmux set-progress 0.4 --label "2/5 workers done"
cmux notify --title "Manager" --body "worker-3 is blocked on a question"

Manager → worker workflow

The pattern from the workshop: the human is the CEO and talks only to you, the Manager, in the focused pane. You coordinate worker panes; workers do research/implementation.

1. Plan with the human first. Agree on how many workers and what each does. Don't fan out on ambiguity.
2. Build the layout. cmux new-split right / cmux new-pane per worker; cmux rename-tab "<role>" each so they're findable.
3. Delegate. cmux send --surface surface:N -- "<task>\n" into each worker.
4. Inspect, don't assume. Before reporting or acting, cmux --json tree to see current refs, then cmux read-screen --surface surface:N to read each worker's actual output. Never invent output you didn't read.
5. Report up. Summarize worker state to the human. If a worker is blocked on a question, read it, decide (or ask the human), and answer it via send/send-key.

The lesson's full copy-paste Manager prompt and the deeper command catalog are in references/cmux-cli.md.

Answering agents in workers

Workers often run an agent (Claude Code, Codex, opencode) that pauses on a question or approval. The move is always: read-screen first, then respond to what you actually see. Two shapes:

• Free-text / chat prompt (agent asks a question and waits for a typed reply): send the answer with a trailing newline to submit. cmux send --surface surface:2 -- "Yes — prefer the existing util, don't add a dep\n"

• TUI selection menu (Claude Code permission prompt, Codex approval, y/N confirms): these capture keystrokes, not a line of text. Read which option you want, then drive the keys.

  • Numbered menu → send the number: cmux send-key --surface surface:2 -- "1"
  • Highlighted list → cmux send-key --surface surface:2 down then cmux send-key --surface surface:2 enter
  • Plain [y/N] → cmux send-key --surface surface:2 -- "y" then (if needed) enter
  • Need to interrupt a runaway worker → cmux send-key --surface surface:2 ctrl+c

Exact keys vary by the worker's TUI and change between versions, so don't memorize a mapping — read the screen, then send the matching key. Re-read with read-screen afterward to confirm the prompt was accepted.

AFK check-in loop

For "set it and walk away" runs, give a bounded goal with an interval and a stop condition (the workshop pattern). Example shape to hand a Manager pane:

Record a start timestamp. Every 10 minutes, cmux --json tree then cmux read-screen each worker surface; if a worker is blocked on a question, read it and pick the best answer (or cmux notify me if it's a real decision); otherwise nudge it to continue. Stop 4 hours after the start timestamp and post a final summary.

Keep the upfront planning human-led; only the periodic mechanical check-ins run unattended.

When you need more

• Full command catalog, JSON tree shape, and gotchas: references/cmux-cli.md
• Authoritative, always-current: cmux help, cmux <command> --help, cmux docs <topic> (settings|shortcuts|api|browser|agents|dock|sidebars).