Cmux Terminal Multiplexer

1---2name: cmux-terminal-multiplexer3description: AI-native terminal multiplexer with programmable socket API, full Playwright-equivalent browser automation, and agent team coordination — built for Claude Code and autonomous agent workflows4triggers:5  - "use cmux to open a split"6  - "cmux browser automation"7  - "open a terminal split with cmux"8  - "control browser with cmux"9  - "cmux agent workspace coordination"10  - "set up cmux splits for parallel work"11  - "cmux send command to terminal"12  - "automate browser with cmux"13---14 15# cmux — AI-Native Terminal Multiplexer16 17> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection18 19cmux is a terminal multiplexer with a programmable socket API designed for AI coding agents. It provides full Playwright-equivalent browser automation, real-time terminal split management, sidebar status reporting, and agent team coordination — all via a simple CLI.20 21---22 23## What cmux Does24 25- **Terminal splits** — create side-by-side or stacked panes, send commands, capture output26- **Browser automation** — full headless Chromium with snapshot-based element refs (no CSS selectors)27- **Status sidebar** — live progress bars, log messages, and icon badges visible to the user28- **Notifications** — native OS notifications from agent workflows29- **Agent teams** — coordinate parallel subagents, each with their own visible split30 31---32 33## Orient Yourself34 35```bash36cmux identify --json          # current window/workspace/pane/surface context37cmux list-panes               # all panes in current workspace38cmux list-pane-surfaces --pane pane:1  # surfaces within a pane39cmux list-workspaces          # all workspaces (tabs) in current window40```41 42Environment variables set automatically:43- `$CMUX_SURFACE_ID` — your current surface ref44- `$CMUX_WORKSPACE_ID` — your current workspace ref45 46Handles use short refs: `surface:N`, `pane:N`, `workspace:N`, `window:N`.47 48---49 50## Terminal Splits51 52### Create splits53 54```bash55cmux --json new-split right   # side-by-side (preferred for parallel work)56cmux --json new-split down    # stacked (good for logs)57```58 59Always capture the returned `surface_ref`:60 61```bash62WORKER=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")63```64 65### Send commands and read output66 67```bash68cmux send-surface --surface surface:22 "npm run build\n"69cmux capture-pane --surface surface:22              # current screen70cmux capture-pane --surface surface:22 --scrollback  # with full history71 72cmux send-key-surface --surface surface:22 ctrl-c  # send key73cmux send-key-surface --surface surface:22 enter74```75 76**Golden rule: never steal focus.** Always use `--surface` targeting.77 78### Worker split pattern79 80```bash81WORKER=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")82cmux send-surface --surface "$WORKER" "make test 2>&1; echo EXIT_CODE=\$?\n"83sleep 384cmux capture-pane --surface "$WORKER"85cmux close-surface --surface "$WORKER"   # clean up when done86```87 88### Pane management89 90```bash91cmux focus-pane --pane pane:292cmux close-surface --surface surface:2293cmux swap-pane --pane pane:1 --target-pane pane:294cmux move-surface --surface surface:7 --pane pane:2 --focus true95cmux reorder-surface --surface surface:7 --before surface:396```97 98---99 100## Browser Automation101 102cmux embeds a full headless Chromium engine with a Playwright-style API. No external Chrome required. Every command targets a browser surface by ref.103 104### Workflow pattern105 106```107navigate → wait for load → snapshot --interactive → act with refs → re-snapshot108```109 110### Open and navigate111 112```bash113cmux --json browser open https://example.com        # opens browser split, returns surface ref114cmux browser surface:23 goto https://other.com115cmux browser surface:23 back116cmux browser surface:23 forward117cmux browser surface:23 reload118cmux browser surface:23 get url119cmux browser surface:23 get title120```121 122Capture the surface ref:123 124```bash125BROWSER=$(cmux --json browser open https://docs.example.com | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")126```127 128### Snapshot and element refs129 130Instead of CSS selectors, snapshot to get stable element refs (`e1`, `e2`, ...):131 132```bash133cmux browser surface:23 snapshot --interactive              # full interactive snapshot134cmux browser surface:23 snapshot --interactive --compact     # compact output135cmux browser surface:23 snapshot --selector "form#login" --interactive  # scoped136```137 138Refs are invalidated after DOM mutations — always re-snapshot after navigation or clicks. Use `--snapshot-after` to auto-get a fresh snapshot:139 140```bash141cmux --json browser surface:23 click e1 --snapshot-after142```143 144### Interact with elements145 146```bash147# Click and hover148cmux browser surface:23 click e1149cmux browser surface:23 dblclick e2150cmux browser surface:23 hover e3151cmux browser surface:23 focus e4152 153# Text input154cmux browser surface:23 fill e5 "hello@example.com"   # clear + type155cmux browser surface:23 fill e5 ""                      # clear input156cmux browser surface:23 type e6 "search query"          # type without clearing157 158# Keys159cmux browser surface:23 press Enter160cmux browser surface:23 press Tab161cmux browser surface:23 keydown Shift162 163# Forms164cmux browser surface:23 check e7          # checkbox165cmux browser surface:23 uncheck e7166cmux browser surface:23 select e8 "option-value"167 168# Scroll169cmux browser surface:23 scroll --dy 500170cmux browser surface:23 scroll --selector ".container" --dy 300171cmux browser surface:23 scroll-into-view e9172```173 174### Wait for state175 176```bash177cmux browser surface:23 wait --load-state complete --timeout-ms 15000178cmux browser surface:23 wait --selector "#ready" --timeout-ms 10000179cmux browser surface:23 wait --text "Success" --timeout-ms 10000180cmux browser surface:23 wait --url-contains "/dashboard" --timeout-ms 10000181cmux browser surface:23 wait --function "document.readyState === 'complete'" --timeout-ms 10000182```183 184### Read page content185 186```bash187cmux browser surface:23 get text body        # visible text188cmux browser surface:23 get html body        # raw HTML189cmux browser surface:23 get value "#email"   # input value190cmux browser surface:23 get attr "#link" --attr href191cmux browser surface:23 get count ".items"   # element count192cmux browser surface:23 get box "#button"    # bounding box193cmux browser surface:23 get styles "#el" --property color194 195# State checks196cmux browser surface:23 is visible "#modal"197cmux browser surface:23 is enabled "#submit"198cmux browser surface:23 is checked "#agree"199```200 201### Locators (Playwright-style)202 203```bash204cmux browser surface:23 find role button205cmux browser surface:23 find text "Sign In"206cmux browser surface:23 find label "Email"207cmux browser surface:23 find placeholder "Enter email"208cmux browser surface:23 find testid "submit-btn"209cmux browser surface:23 find first ".item"210cmux browser surface:23 find last ".item"211cmux browser surface:23 find nth ".item" 3212```213 214### JavaScript evaluation215 216```bash217cmux browser surface:23 eval "document.title"218cmux browser surface:23 eval "document.querySelectorAll('.item').length"219cmux browser surface:23 eval "window.scrollTo(0, document.body.scrollHeight)"220```221 222### Frames and dialogs223 224```bash225cmux browser surface:23 frame "#iframe-selector"   # switch to iframe226cmux browser surface:23 frame main                  # back to main frame227cmux browser surface:23 dialog accept228cmux browser surface:23 dialog dismiss229cmux browser surface:23 dialog accept "prompt text"230```231 232### Cookies, storage, and state233 234```bash235# Cookies236cmux browser surface:23 cookies get237cmux browser surface:23 cookies set session_token "abc123"238cmux browser surface:23 cookies clear239 240# Local/session storage241cmux browser surface:23 storage local get242cmux browser surface:23 storage local set myKey "myValue"243cmux browser surface:23 storage session clear244 245# Save/restore full browser state (cookies + storage + tabs)246cmux browser surface:23 state save ./auth-state.json247cmux browser surface:23 state load ./auth-state.json248```249 250### Authentication flow251 252```bash253BROWSER=$(cmux --json browser open https://app.example.com/login | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")254cmux browser $BROWSER wait --load-state complete --timeout-ms 15000255cmux browser $BROWSER snapshot --interactive256cmux browser $BROWSER fill e1 "user@example.com"257cmux browser $BROWSER fill e2 "my-password"258cmux browser $BROWSER click e3259cmux browser $BROWSER wait --url-contains "/dashboard" --timeout-ms 20000260 261# Save auth for reuse262cmux browser $BROWSER state save ./auth-state.json263 264# Reuse in a new surface265BROWSER2=$(cmux --json browser open https://app.example.com | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")266cmux browser $BROWSER2 state load ./auth-state.json267cmux browser $BROWSER2 goto https://app.example.com/dashboard268```269 270### Diagnostics271 272```bash273cmux browser surface:23 console list     # JS console output274cmux browser surface:23 console clear275cmux browser surface:23 errors list      # JS errors276cmux browser surface:23 errors clear277cmux browser surface:23 highlight "#el"  # visual highlight278cmux browser surface:23 screenshot       # capture screenshot279```280 281### Script and style injection282 283```bash284cmux browser surface:23 addscript "console.log('injected')"285cmux browser surface:23 addstyle "body { background: red; }"286cmux browser surface:23 addinitscript "window.__injected = true"  # runs on every nav287```288 289---290 291## Sidebar Status and Progress292 293Show live status to the user without interrupting their flow:294 295```bash296cmux set-status agent "working" --icon hammer --color "#ff9500"297cmux set-status agent "done" --icon checkmark --color "#34c759"298cmux clear-status agent299 300cmux set-progress 0.3 --label "Running tests..."301cmux set-progress 1.0 --label "Complete"302cmux clear-progress303 304cmux log "Starting build"305cmux log --level success "All tests passed"306cmux log --level error --source build "Compilation failed"307```308 309---310 311## Notifications312 313```bash314cmux notify --title "Task Complete" --body "All tests passing"315cmux notify --title "Need Input" --subtitle "Permission" --body "Approve deployment?"316```317 318---319 320## Agent Teams with cmux321 322Use cmux splits to give each agent teammate a visible workspace. Coordinate via `SendMessage` and task lists — never via reading each other's terminal output.323 324### The pattern325 3261. Create splits for each teammate3272. Spawn teammates via Agent tool — pass each their cmux surface ref3283. Teammates run commands in their split via `cmux send-surface`3294. Teammates report status via `cmux set-status` and `cmux log`3305. User sees all work side-by-side331 332### Example: 3-agent team333 334```bash335# Create visible splits for each teammate336SPLIT_1=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")337SPLIT_2=$(cmux --json new-split down | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")338SPLIT_3=$(cmux --json new-split down | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")339```340 341Then in each teammate's prompt:342```343You have a cmux terminal split at surface:42.344Run commands:  cmux send-surface --surface surface:42 "command\n"345Read output:   cmux capture-pane --surface surface:42346Set status:    cmux set-status myagent "working" --icon hammer347Log progress:  cmux log "message"348Never steal focus — always use --surface targeting.349```350 351### Mixed layout: terminals + browsers352 353```bash354BUILD=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")355DOCS=$(cmux --json browser open https://docs.example.com | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")356TEST=$(cmux --json new-split down | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")357```358 359### Key rules360 361- **Never spawn `claude -p` in splits** — use the Agent tool with `team_name` instead362- **Create splits before spawning teammates** — pass refs in their prompts363- **One split per teammate** — each owns their visible workspace364- **Coordinate via SendMessage**, not by reading each other's terminal output365- **Clean up**: `cmux close-surface --surface <ref>` when done366 367---368 369## Quick Reference370 371| Task | Command |372|------|---------|373| Where am I? | `cmux identify --json` |374| Split right | `cmux --json new-split right` |375| Split down | `cmux --json new-split down` |376| Send command | `cmux send-surface --surface <ref> "cmd\n"` |377| Read output | `cmux capture-pane --surface <ref>` |378| Open browser | `cmux --json browser open <url>` |379| Page snapshot | `cmux browser <ref> snapshot --interactive` |380| Click element | `cmux browser <ref> click e1` |381| Fill input | `cmux browser <ref> fill e1 "text"` |382| Wait for load | `cmux browser <ref> wait --load-state complete --timeout-ms 15000` |383| Read page text | `cmux browser <ref> get text body` |384| Evaluate JS | `cmux browser <ref> eval "expression"` |385| Find by role | `cmux browser <ref> find role button` |386| Save auth | `cmux browser <ref> state save ./auth.json` |387| Load auth | `cmux browser <ref> state load ./auth.json` |388| Set status | `cmux set-status <key> "text" --icon <name>` |389| Progress bar | `cmux set-progress 0.5 --label "Working..."` |390| Log message | `cmux log "message"` |391| Notify | `cmux notify --title "T" --body "B"` |392| Close split | `cmux close-surface --surface <ref>` |393| Screenshot | `cmux browser <ref> screenshot` |394 395---396 397## Common Patterns398 399### Run build in background split, tail logs400 401```bash402LOG=$(cmux --json new-split down | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")403cmux send-surface --surface "$LOG" "cargo build --release 2>&1 | tee /tmp/build.log\n"404# ... do other work ...405cmux capture-pane --surface "$LOG" --scrollback | tail -20406```407 408### QA test flow409 410```bash411BROWSER=$(cmux --json browser open https://myapp.vercel.app | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")412cmux browser $BROWSER wait --load-state complete --timeout-ms 15000413cmux browser $BROWSER snapshot --interactive414# Interact using e1, e2, e3 refs...415cmux browser $BROWSER screenshot416cmux browser $BROWSER errors list417cmux close-surface --surface $BROWSER418```419 420### Status-driven long task421 422```bash423cmux set-status task "starting" --icon clock --color "#ff9500"424cmux set-progress 0.0 --label "Initializing..."425 426# ... step 1 ...427cmux set-progress 0.33 --label "Building..."428 429# ... step 2 ...430cmux set-progress 0.66 --label "Testing..."431 432# ... step 3 ...433cmux set-progress 1.0 --label "Done"434cmux set-status task "complete" --icon checkmark --color "#34c759"435cmux clear-progress436cmux notify --title "Task complete" --body "All steps passed"437```