cli-cmux

# cmux — Terminal Multiplexer with Native Browser cmux manages terminal panes and browser views through a Unix socket CLI. You are already running inside cmux — your current pane has env vars `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID` set automatically. ## Mental Model ``` window → workspace(s) → pane(s) → surface(s) ↑ terminal OR browser ``` - **Window**: OS window - **Workspace**: A tab within a window (like tmux sessions) - **Pane**: A visual split region - **Surface**: The content inside a pane (terminal or browser); panes can have multiple surfaces as tabs ## Addressing cmux uses **short refs** by default: `workspace:1`, `pane:2`, `surface:3`. Most commands auto-target the caller's workspace/surface via env vars. ```bash # Discover current layout cmux identify # What workspace/pane/surface am I in? cmux list-panes # Panes in current workspace cmux list-workspaces # All workspaces ``` ## Core Operations ### Layout — Splits and Panes ```bash # Create a new terminal pane (split from current) cmux new-pane --direction right cmux new-pane --direction down # Create a browser pane cmux new-pane --type browser --direction right --url http://localhost:3000 # Focus a pane cmux focus-pane --pane pane:3 # Resize cmux resize-pane --pane pane:2 -R --amount 20 # grow rightward cmux resize-pane --pane pane:2 -D --amount 10 # grow downward ``` ### Terminal I/O — Read and Send ```bash # Read what's on screen in another pane cmux read-screen --surface surface:2 cmux read-screen --surface surface:2 --scrollback --lines 100 # Send text (like typing) cmux send --surface surface:2 "npm run dev" cmux send --surface surface:2 $'\n' # press Enter # Send special keys cmux send-key --surface surface:2 Enter cmux send-key --surface surface:2 Up cmux send-key --surface surface:2 Ctrl+C ``` ### Browser — Navigate and Interact ```bash # Open URL in an existing browser surface cmux browser --surface surface:3 navigate http://localhost:3000 # Snapshot the DOM (interactive elements) cmux browser --surface surface:3 snapshot --interactive # Click, fill, type using CSS selectors cmux browser --surface surface:3 click "button.submit" cmux browser --surface surface:3 fill "input[name=email]" "test@example.com" cmux browser --surface surface:3 type "input[name=search]" "query" # Press keys, scroll cmux browser --surface surface:3 press Enter cmux browser --surface surface:3 scroll --dy 500 # Read state cmux browser --surface surface:3 get url cmux browser --surface surface:3 get title cmux browser --surface surface:3 get text "h1" # Wait for conditions cmux browser --surface surface:3 wait --selector ".loaded" cmux browser --surface surface:3 wait --load-state complete cmux browser --surface surface:3 wait --text "Dashboard" ``` --- ## Workflow: Testing a Web UI The pattern: start the dev server in a terminal pane, open a browser pane pointing at it, then interact via snapshot → act → re-snapshot. ```bash # 1. Start dev server in a new pane cmux new-pane --direction down # note the surface ref from output, e.g. surface:2 cmux send --surface surface:2 "npm run dev" cmux send-key --surface surface:2 Enter # 2. Wait for server to be ready # (read screen until you see the ready message) cmux read-screen --surface surface:2 # 3. Open browser pane pointing at dev server cmux new-pane --type browser --direction right --url http://localhost:3000 # note the browser surface ref, e.g. surface:3 # 4. Snapshot → interact → re-snapshot loop cmux browser --surface surface:3 snapshot --interactive cmux browser --surface surface:3 click "nav a[href='/settings']" cmux browser --surface surface:3 wait --load-state complete cmux browser --surface surface:3 snapshot --interactive # 5. Fill a form cmux browser --surface surface:3 fill "input[name=username]" "testuser" cmux browser --surface surface:3 fill "input[name=password]" "secret" cmux browser --surface surface:3 click "button[type=submit]" cmux browser --surface surface:3 wait --text "Welcome" cmux browser --surface surface:3 snapshot --interactive ``` ### Snapshot Tips - `--interactive` returns only interactive elements — much smaller output - `--compact` reduces whitespace for smaller snapshots - `--selector "main"` scopes to a region of the page - `--max-depth 5` limits DOM tree depth - Always re-snapshot after navigation or DOM mutations ## Workflow: Testing a TUI The pattern: launch the TUI in a new pane, read-screen to observe, send/send-key to interact. ```bash # 1. Launch the TUI cmux new-pane --direction right # note surface ref, e.g. surface:2 cmux send --surface surface:2 "my-cli-wizard" cmux send-key --surface surface:2 Enter # 2. Read → interact → read loop cmux read-screen --surface surface:2 cmux send-key --surface surface:2 ArrowDown cmux send-key --surface surface:2 ArrowDown cmux send-key --surface surface:2 Enter cmux read-screen --surface surface:2 # 3. Type text input cmux send --surface surface:2 "my-project-name" cmux send-key --surface surface:2 Enter cmux read-screen --surface surface:2 # 4. Test cancellation cmux send-key --surface surface:2 Ctrl+C cmux read-screen --surface surface:2 # 5. Clean up cmux send-key --surface surface:2 Ctrl+C ``` ### TUI Tips - Use `read-screen` (not `read-screen --scrollback`) for current viewport - Add `--lines 50` with `--scrollback` to limit output size - Send `Ctrl+C` to kill the TUI when done - Read the screen after each interaction to confirm state changes ## Context Management cmux interactions are context-expensive. Minimize round-trips: 1. **Batch related commands** — don't read-screen between every single keystroke 2. **Use `--interactive` and `--compact`** for browser snapshots 3. **Scope snapshots** with `--selector` when you only care about part of the page 4. **Delegate long test sessions to a Task subagent** — the subagent runs the full interaction loop and returns only findings ## Sidebar Metadata cmux provides sidebar status, progress, and logging for visibility: ```bash cmux set-status "phase" "testing" --icon "🧪" cmux set-progress 0.5 --label "Running tests..." cmux log "Found 3 issues" --level warn cmux clear-progress ``` ## Reference For full command details, see: - [reference/browser-commands.md](reference/browser-commands.md) — All browser subcommands - [reference/terminal-io.md](reference/terminal-io.md) — Terminal read/send/key commands - [reference/layout-commands.md](reference/layout-commands.md) — Pane, workspace, window management