# Cmux > cmux terminal orchestration — split panes, spawn Claude Code instances, send commands, poll output, report sidebar progress, automate the built-in browser, and preview markdown. Use this skill whenever you need to: run parallel tasks in separate panes, launch sub-Claude-Code instances, monitor terminal output, update sidebar status/progress, coordinate multiple terminal sessions, fan out work across splits, open a website in a cmux browser pane, interact with web pages, or display markdown alongside the terminal. Even if the user just says 'run these in parallel', 'open that in a browser', or 'show the plan', this skill applies. - Skill: `jiahao-shao1/cmux-2` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add jiahao-shao1/cmux-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/jiahao-shao1/cmux-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: jiahao-shao1 (https://skillmd.com/u/jiahao-shao1) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jiahao-shao1/cmux-2 --- # 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 ```bash cmux identify --json # your current context cmux list-workspaces # all workspaces cmux list-panes # panes in current workspace cmux list-pane-surfaces --pane # surfaces in a pane cmux tree --all # full hierarchy view ``` ## Create Terminals ```bash cmux new-split # split current pane cmux new-workspace --cwd # 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`. ```bash # Interactive mode — user can switch to this pane and intervene anytime cmux send --surface 'proxy && claude --dangerously-skip-permissions\n' # Non-interactive mode — run a task, capture output, signal completion cmux send --surface 'proxy && claude -p "your prompt" --model haiku 2>&1 | tee /tmp/agent-output.txt; echo "AGENT_DONE"\n' ``` ## Send Input / Read Output ```bash cmux send --surface "text\n" # send text (include \n for Enter) cmux send-key --surface # send special key (ctrl-c, enter, etc.) cmux read-screen --surface --lines # 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. ```bash cmux set-status --icon --color <#hex> cmux set-progress <0.0-1.0> --label "text" cmux log --level --source "agent" -- "message" cmux notify --title "Title" --body "Body" # desktop notification cmux clear-status / cmux clear-progress / cmux clear-log ``` ## Workspace Management ```bash cmux rename-workspace "name" cmux rename-tab --surface "name" cmux close-surface --surface cmux close-workspace --workspace ``` ## Browser (quick reference) Open sites in cmux's built-in browser, interact with pages, take screenshots. Read [references/browser.md](references/browser.md) for full command reference, form automation, and troubleshooting. ```bash cmux --json browser open https://example.com # open browser split, returns surface ref cmux browser wait --load-state complete --timeout-ms 15000 cmux browser snapshot --interactive # get clickable element refs cmux browser click e1 # click element by ref cmux browser fill e2 "text" # fill input field cmux browser screenshot --out /tmp/s.png # take screenshot cmux browser get url # current URL cmux browser get title # page title cmux browser navigate # go to URL ``` ## Markdown Preview (quick reference) Display formatted markdown alongside the terminal with live reload. Read [references/markdown.md](references/markdown.md) for routing options and agent integration patterns. ```bash 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) ```bash 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) ```bash 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 ```bash 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 ` 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.