cmux-browser

cmux Browser

Use this skill for browser automation inside cmux webview surfaces. It is different from a standalone browser automation tool because every browser surface lives inside a cmux workspace, pane, and surface topology.

Default Rule

Open and control browser surfaces in the current caller workspace unless the user explicitly names another workspace or window.

Before mutating browser state, identify the caller:

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

Use CMUX_WORKSPACE_ID for new browser splits and CMUX_SURFACE_ID to understand the terminal that invoked the automation. Do not open a browser in the visually focused workspace if it differs from the caller workspace.

Core Workflow

# Open in the caller workspace and capture the returned surface ref.
cmux --json browser open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}"

# Use the returned surface, for example surface:7.
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 click e2 --snapshot-after
cmux browser surface:7 snapshot --interactive --compact

Loop: navigate, verify URL, wait, snapshot, act, then re-snapshot. Snapshot refs are temporary. Re-snapshot after navigation, modal changes, tab changes, or DOM updates.

Targeting

Most subcommands require a browser surface:

cmux browser identify
cmux browser identify --surface surface:2
cmux browser surface:2 get url
cmux browser --surface surface:2 get title

Open commands can create or reuse a browser split:

cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux browser open-split https://example.com --workspace workspace:2 --json
cmux browser new https://example.com --window window:1 --json

Keep one browser surface per task unless the user asks for multiple tabs or pages.

Command Groups

See references/commands.md for the full command list. Main groups:

• Navigation and targeting: identify, open, open-split, new, navigate, goto, back, forward, reload, url, focus-webview, is-webview-focused.
• Waiting: wait --selector, --text, --url-contains, --load-state, --function.
• DOM interaction: click, dblclick, hover, focus, check, uncheck, scroll-into-view, type, fill, press, keydown, keyup, select, scroll.
• Inspection: snapshot, screenshot, get, is, find, highlight.
• JavaScript and injection: eval, addinitscript, addscript, addstyle.
• Frames, dialogs, downloads: frame, dialog, download.
• State and session: cookies, storage, state.
• Tabs and diagnostics: tab, console, errors.
• Environment and lower-level APIs: viewport, geolocation, offline, trace, network, screencast, input.

Common Patterns

Durable Captures

Save browser screenshots, traces, downloaded diagnostics, and reusable session state under /cmux-assets/<branch>/browser/..., not /tmp, before reporting them to the user.

BRANCH="$(git branch --show-current 2>/dev/null || true)"
BRANCH="${BRANCH:-$(basename "$PWD")}"
BRANCH="$(printf '%s' "$BRANCH" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//;s/-$//')"
ASSET_BASE="/cmux-assets"
if ! mkdir -p "$ASSET_BASE/$BRANCH" 2>/dev/null; then
  ASSET_BASE="$(pwd)/cmux-assets"
  mkdir -p "$ASSET_BASE/$BRANCH"
fi
BROWSER_ASSET_ROOT="$ASSET_BASE/$BRANCH/browser/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BROWSER_ASSET_ROOT"

If /cmux-assets is unavailable because the root volume is read-only, use the fallback path and state it. Do not leave final screenshots or session files only in /tmp.

Navigate, Wait, Inspect

cmux --json browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 get title

Form Fill

cmux browser surface:7 fill "#email" --text "[email protected]"
cmux browser surface:7 fill "#password" --text "$PASSWORD"
cmux browser surface:7 click "button[type='submit']" --snapshot-after
cmux browser surface:7 wait --text "Welcome" --timeout-ms 15000
cmux browser surface:7 is visible "#dashboard"

Debug Capture

cmux browser surface:7 console list
cmux browser surface:7 errors list
cmux browser surface:7 screenshot --out "$BROWSER_ASSET_ROOT/cmux-failure.png"
cmux browser surface:7 snapshot --interactive --compact

Session Save and Restore

cmux browser surface:7 state save "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 state load "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 reload --snapshot-after

Remote Workspaces

In remote SSH workspaces, browser panes route HTTP and WebSocket traffic through the remote machine. localhost:3000 means the remote host's localhost, and browser storage is isolated per remote workspace context.

Rebuild and Reload

If browser automation is validating a cmux app/runtime change, first build a tagged app from the active worktree:

./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"

Never automate against an untagged debug socket for tests or dogfood builds.

Rules

• Scope browser opens and actions to the current caller workspace by default.
• Pass --workspace "${CMUX_WORKSPACE_ID:-}" when creating a browser surface from a cmux terminal.
• Use returned surface:N refs, and re-snapshot after any state-changing action.
• Verify get url before waiting or diagnosing page state.
• Use --snapshot-after on mutating actions when you need immediate verification.
• Prefer get, is, and find for scripts. Use screenshots and snapshots for human review.
• Do not close, move, or focus browser surfaces outside the caller workspace unless the user names that target.
• Do not use unsupported standalone-browser assumptions. cmux uses WKWebView-backed browser surfaces.