cmux-orchestrate

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.

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, it must receive Enter. For short commands, ending the text with \n works (\n/\r → Enter, \t → Tab). For long prompts, a trailing \n is often swallowed into a bracketed paste — send the text first, then submit with a separate cmux send-key --surface surface:N enter.
5. Single-quote free text — never double-quote it. Always pass task text as -- '<task>'. Inside double quotes the shell expands $(), backticks, and $VAR in YOUR (manager) shell before cmux ever sees the text — command injection and credential leakage. If the text itself needs a single quote, rephrase to avoid it (e.g. don't → do not).
6. Prefer panes over tab groups — tab groups are easy to lose track of.
7. Keep upfront planning human-led. Confirm the layout/plan with the user before fanning out workers.
8. Pick the worker model and effort deliberately. Workers don't need the orchestrator's model tier — a cheaper model (e.g. claude --model sonnet) keeps cost and latency down. Effort follows the task: high for open-ended research or investigation; medium for well-specified implementation against a locked plan (the orchestrate-plan skill mandates this). This applies only to workers you spawn, never to the Manager pane (you).