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.