End-user browser automation with cmux. Use when you need to open sites, interact with pages, wait for state changes, and extract data from cmux browser surfaces.
Use this skill for browser tasks inside cmux webviews.
get url before waiting or snapshotting.--interactive) to get fresh element refs.click, fill, type, select, press).cmux --json browser open https://example.com
# use returned surface ref, 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
cmux browser surface:7 fill e1 "hello"
cmux --json browser surface:7 click e2 --snapshot-after
cmux browser surface:7 snapshot --interactive
# identify current context
cmux identify --json
# open routed to a specific topology target
cmux browser open https://example.com --workspace workspace:2 --window window:1 --json
Notes:
surface:N, pane:N, workspace:N, window:N).--id-format uuids|both).surface:N per task unless you intentionally switch.cmux supports wait patterns similar to agent-browser:
cmux browser <surface> wait --selector "#ready" --timeout-ms 10000
cmux browser <surface> wait --text "Success" --timeout-ms 10000
cmux browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000
cmux --json browser open https://example.com/signup
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e1 "Jane Doe"
cmux browser surface:7 fill e2 "[email protected]"
cmux --json browser surface:7 click e3 --snapshot-after
cmux browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e11 "" --snapshot-after --json
cmux browser surface:7 get value e11 --json
# navigate -> verify -> wait -> snapshot -> action -> snapshot
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux --json browser surface:7 click e5 --snapshot-after
cmux browser surface:7 snapshot --interactive
If get url is empty or about:blank, navigate first instead of waiting on load state.
| Reference | When to Use |
|---|---|
| references/commands.md | Full browser command mapping and quick syntax |
| references/snapshot-refs.md | Ref lifecycle and stale-ref troubleshooting |
| references/authentication.md | Login/OAuth/2FA patterns and state save/load |
| references/authentication.md#saving-authentication-state | Save authenticated state right after login |
| references/session-management.md | Multi-surface isolation and state persistence patterns |
| references/video-recording.md | Current recording status and practical alternatives |
| references/proxy-support.md | Proxy behavior in WKWebView and workarounds |
| Template | Description |
|---|---|
| templates/form-automation.sh | Snapshot/ref form fill loop |
| templates/authenticated-session.sh | Login once, save/load state |
| templates/capture-workflow.sh | Navigate + capture snapshots/screenshots |
These commands currently return not_supported because they rely on Chrome/CDP-only APIs not exposed by WKWebView:
Use supported high-level commands (click, fill, press, scroll, wait, snapshot) instead.
js_error on snapshot --interactive or evalSome complex pages can reject or break the JavaScript used for rich snapshots and ad-hoc evaluation.
Recovery steps:
cmux browser surface:7 get url
cmux browser surface:7 get text body
cmux browser surface:7 get html body
get url first so you know whether the page actually navigated.get text body or get html body when snapshot --interactive or eval returns js_error.