cmux Orchestration

Orchestrate terminal sessions, spawn Claude Code instances, automate the built-in browser, preview markdown — all inside cmux.

Detection

Check CMUX_WORKSPACE_ID env var. If set → you're in cmux. If unset → skip all cmux commands.

Auto-set env vars: CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH.

Hierarchy

Window > Workspace (sidebar tab) > Pane (split region) > Surface (terminal tab in pane).

Short refs: workspace:1, pane:1, surface:2.

Orientation

cmux identify --json                              # your current context
cmux list-workspaces                              # all workspaces
cmux list-panes                                   # panes in current workspace
cmux list-pane-surfaces --pane <ref>              # surfaces in a pane
cmux tree --all                                   # full hierarchy view

Create Terminals

cmux new-split <left|right|up|down>               # split current pane
cmux new-workspace --cwd <path>                   # new workspace tab
cmux new-surface                                  # new tab in current pane

Launch Claude Code in a Pane

Network access requires proxy. Always include it before claude.

# Interactive mode — user can switch to this pane and intervene anytime
cmux send --surface <ref> 'proxy && claude --dangerously-skip-permissions\n'

# Non-interactive mode — run a task, capture output, signal completion
cmux send --surface <ref> 'proxy && claude -p "your prompt" --model haiku 2>&1 | tee /tmp/agent-output.txt; echo "AGENT_DONE"\n'

Send Input / Read Output

cmux send --surface <ref> "text\n"                # send text (include \n for Enter)
cmux send-key --surface <ref> <key>               # send special key (ctrl-c, enter, etc.)
cmux read-screen --surface <ref> --lines <n>      # read last n lines of terminal output

Sidebar Status & Progress

The sidebar is always visible — use it to give the user a glance at what's happening without switching panes.

cmux set-status <key> <value> --icon <name> --color <#hex>
cmux set-progress <0.0-1.0> --label "text"
cmux log --level <info|success|warning|error> --source "agent" -- "message"
cmux notify --title "Title" --body "Body"         # desktop notification
cmux clear-status <key> / cmux clear-progress / cmux clear-log

Workspace Management

cmux rename-workspace "name"
cmux rename-tab --surface <ref> "name"
cmux close-surface --surface <ref>
cmux close-workspace --workspace <ref>

Browser (quick reference)

Open sites in cmux's built-in browser, interact with pages, take screenshots. Read references/browser.md for full command reference, form automation, and troubleshooting.

cmux --json browser open https://example.com      # open browser split, returns surface ref
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> snapshot --interactive      # get clickable element refs
cmux browser <surface> click e1                    # click element by ref
cmux browser <surface> fill e2 "text"              # fill input field
cmux browser <surface> screenshot --out /tmp/s.png # take screenshot
cmux browser <surface> get url                     # current URL
cmux browser <surface> get title                   # page title
cmux browser <surface> navigate <url>              # go to URL

Markdown Preview (quick reference)

Display formatted markdown alongside the terminal with live reload. Read references/markdown.md for routing options and agent integration patterns.

cmux markdown open plan.md                         # open preview panel (auto-reloads on file change)
cmux markdown open plan.md --workspace workspace:2 # target specific workspace

Workflow Patterns

Fan out into splits (parallel tasks)

cmux new-split right
cmux send --surface surface:2 'proxy && claude -p "analyze project structure" --model haiku > /tmp/a1.txt; echo "DONE"\n'

cmux new-split down
cmux send --surface surface:3 'proxy && claude -p "count code lines" --model haiku > /tmp/a2.txt; echo "DONE"\n'

cmux set-status task "Running" --icon hammer --color "#1565C0"
# Poll: cmux read-screen --surface surface:2 --lines 5
# Collect: cat /tmp/a1.txt /tmp/a2.txt
# Clean up: cmux close-surface --surface surface:2 && cmux close-surface --surface surface:3

Interactive sub-agents (user can intervene)

cmux new-split right
cmux send --surface surface:2 'proxy && claude --dangerously-skip-permissions\n'
# User can ⌥⌘→ to switch to that pane and talk to the sub-agent directly

Progress tracking

cmux set-progress 0.0 --label "Starting"
# ... work ...
cmux set-progress 0.5 --label "Testing"
# ... work ...
cmux set-progress 1.0 --label "Complete"
cmux clear-progress
cmux notify --title "Done" --body "All tasks finished"

Safety Rules

• Don't send to surfaces you didn't create — the user may be actively typing there.
• Always target by surface ref — use --surface <ref> from when you created the pane.
• Don't steal focus — avoid select-workspace, focus-pane unless the user asked.
• Clean up after yourself — close surfaces/workspaces you created once done.
• Start with identify --json — know your context before creating terminals.