Cmux Terminal Multiplexer

cmux — AI-Native Terminal Multiplexer

Skill by ara.so — Daily 2026 Skills collection

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

What cmux Does

• Terminal splits — create side-by-side or stacked panes, send commands, capture output
• Browser automation — full headless Chromium with snapshot-based element refs (no CSS selectors)
• Status sidebar — live progress bars, log messages, and icon badges visible to the user
• Notifications — native OS notifications from agent workflows
• Agent teams — coordinate parallel subagents, each with their own visible split

Orient Yourself

cmux identify --json          # current window/workspace/pane/surface context
cmux list-panes               # all panes in current workspace
cmux list-pane-surfaces --pane pane:1  # surfaces within a pane
cmux list-workspaces          # all workspaces (tabs) in current window

Environment variables set automatically:

• $CMUX_SURFACE_ID — your current surface ref
• $CMUX_WORKSPACE_ID — your current workspace ref

Handles use short refs: surface:N, pane:N, workspace:N, window:N.

Terminal Splits

Create splits

cmux --json new-split right   # side-by-side (preferred for parallel work)
cmux --json new-split down    # stacked (good for logs)

Always capture the returned surface_ref:

WORKER=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")

Send commands and read output

cmux send-surface --surface surface:22 "npm run build\n"
cmux capture-pane --surface surface:22              # current screen
cmux capture-pane --surface surface:22 --scrollback  # with full history

cmux send-key-surface --surface surface:22 ctrl-c  # send key
cmux send-key-surface --surface surface:22 enter

Golden rule: never steal focus. Always use --surface targeting.

Worker split pattern

WORKER=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")
cmux send-surface --surface "$WORKER" "make test 2>&1; echo EXIT_CODE=\$?\n"
sleep 3
cmux capture-pane --surface "$WORKER"
cmux close-surface --surface "$WORKER"   # clean up when done

Pane management

cmux focus-pane --pane pane:2
cmux close-surface --surface surface:22
cmux swap-pane --pane pane:1 --target-pane pane:2
cmux move-surface --surface surface:7 --pane pane:2 --focus true
cmux reorder-surface --surface surface:7 --before surface:3

Browser Automation

cmux embeds a full headless Chromium engine with a Playwright-style API. No external Chrome required. Every command targets a browser surface by ref.

Workflow pattern

navigate → wait for load → snapshot --interactive → act with refs → re-snapshot

Open and navigate

cmux --json browser open https://example.com        # opens browser split, returns surface ref
cmux browser surface:23 goto https://other.com
cmux browser surface:23 back
cmux browser surface:23 forward
cmux browser surface:23 reload
cmux browser surface:23 get url
cmux browser surface:23 get title

Capture the surface ref:

BROWSER=$(cmux --json browser open https://docs.example.com | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")

Snapshot and element refs

Instead of CSS selectors, snapshot to get stable element refs (e1, e2, ...):

cmux browser surface:23 snapshot --interactive              # full interactive snapshot
cmux browser surface:23 snapshot --interactive --compact     # compact output
cmux browser surface:23 snapshot --selector "form#login" --interactive  # scoped

Refs are invalidated after DOM mutations — always re-snapshot after navigation or clicks. Use --snapshot-after to auto-get a fresh snapshot:

cmux --json browser surface:23 click e1 --snapshot-after

Interact with elements

# Click and hover
cmux browser surface:23 click e1
cmux browser surface:23 dblclick e2
cmux browser surface:23 hover e3
cmux browser surface:23 focus e4

# Text input
cmux browser surface:23 fill e5 "hello@example.com"   # clear + type
cmux browser surface:23 fill e5 ""                      # clear input
cmux browser surface:23 type e6 "search query"          # type without clearing

# Keys
cmux browser surface:23 press Enter
cmux browser surface:23 press Tab
cmux browser surface:23 keydown Shift

# Forms
cmux browser surface:23 check e7          # checkbox
cmux browser surface:23 uncheck e7
cmux browser surface:23 select e8 "option-value"

# Scroll
cmux browser surface:23 scroll --dy 500
cmux browser surface:23 scroll --selector ".container" --dy 300
cmux browser surface:23 scroll-into-view e9

Wait for state

cmux browser surface:23 wait --load-state complete --timeout-ms 15000
cmux browser surface:23 wait --selector "#ready" --timeout-ms 10000
cmux browser surface:23 wait --text "Success" --timeout-ms 10000
cmux browser surface:23 wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser surface:23 wait --function "document.readyState === 'complete'" --timeout-ms 10000

Read page content

cmux browser surface:23 get text body        # visible text
cmux browser surface:23 get html body        # raw HTML
cmux browser surface:23 get value "#email"   # input value
cmux browser surface:23 get attr "#link" --attr href
cmux browser surface:23 get count ".items"   # element count
cmux browser surface:23 get box "#button"    # bounding box
cmux browser surface:23 get styles "#el" --property color

# State checks
cmux browser surface:23 is visible "#modal"
cmux browser surface:23 is enabled "#submit"
cmux browser surface:23 is checked "#agree"

Locators (Playwright-style)

cmux browser surface:23 find role button
cmux browser surface:23 find text "Sign In"
cmux browser surface:23 find label "Email"
cmux browser surface:23 find placeholder "Enter email"
cmux browser surface:23 find testid "submit-btn"
cmux browser surface:23 find first ".item"
cmux browser surface:23 find last ".item"
cmux browser surface:23 find nth ".item" 3

JavaScript evaluation

cmux browser surface:23 eval "document.title"
cmux browser surface:23 eval "document.querySelectorAll('.item').length"
cmux browser surface:23 eval "window.scrollTo(0, document.body.scrollHeight)"

Frames and dialogs

cmux browser surface:23 frame "#iframe-selector"   # switch to iframe
cmux browser surface:23 frame main                  # back to main frame
cmux browser surface:23 dialog accept
cmux browser surface:23 dialog dismiss
cmux browser surface:23 dialog accept "prompt text"

Cookies, storage, and state

# Cookies
cmux browser surface:23 cookies get
cmux browser surface:23 cookies set session_token "abc123"
cmux browser surface:23 cookies clear

# Local/session storage
cmux browser surface:23 storage local get
cmux browser surface:23 storage local set myKey "myValue"
cmux browser surface:23 storage session clear

# Save/restore full browser state (cookies + storage + tabs)
cmux browser surface:23 state save ./auth-state.json
cmux browser surface:23 state load ./auth-state.json

Authentication flow

BROWSER=$(cmux --json browser open https://app.example.com/login | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")
cmux browser $BROWSER wait --load-state complete --timeout-ms 15000
cmux browser $BROWSER snapshot --interactive
cmux browser $BROWSER fill e1 "user@example.com"
cmux browser $BROWSER fill e2 "my-password"
cmux browser $BROWSER click e3
cmux browser $BROWSER wait --url-contains "/dashboard" --timeout-ms 20000

# Save auth for reuse