Skill

Fail

Audit score 45

cmux-browser

manaflow-ai/cmux

Browser automation for cmux webviews: open sites, interact with pages, wait for changes, extract data.

What is cmux-browser?

Automate browser tasks within cmux webviews by opening URLs, snapshotting interactive elements, clicking/filling forms, waiting for state changes, and extracting content. Use this when you need reliable end-user browser interaction tied to cmux surfaces.

Open URLs and target browser surfaces with workspace/window routing
Snapshot pages with interactive element references for reliable interaction
Click, fill, type, select, and press keys on page elements
Wait for navigation, load states, selectors, text, URLs, or custom JavaScript conditions
Extract page content via text, HTML, or URL queries
Save and load authenticated session state across surfaces

How to install cmux-browser

npx skills add null --skill cmux-browser

Prerequisites

cmux installed and running
Access to cmux webview surfaces (workspace and window context)

Claude Code

Cursor

Windsurf

Cline

How to use cmux-browser

1.Open a browser surface with `cmux --json browser open <url>` and capture the surface ref
2.Verify navigation with `cmux browser <surface> get url`
3.Wait for page readiness using `cmux browser <surface> wait --load-state complete`
4.Take an interactive snapshot with `cmux browser <surface> snapshot --interactive` to get element refs
5.Interact with elements using refs: `cmux browser <surface> fill <ref> <text>` or `cmux browser <surface> click <ref>`
6.Re-snapshot after DOM or navigation changes to refresh element references
7.Repeat snapshot → action → snapshot for stable, reliable automation

Use cases

Good for

Automate multi-step form submissions with verification between steps
Log in once, save session state, then reuse across multiple tasks
Navigate through multi-page workflows and extract data at each stage
Wait for dynamic content to load before interacting or capturing
Clear form fields and verify input values programmatically

Who it's for

Agents automating web-based workflows
Teams building form-filling or data-extraction bots
Developers testing multi-page user journeys
Anyone needing reliable browser automation tied to cmux topology

cmux-browser FAQ

When should I use snapshot --interactive vs. get text/get html?

Use `snapshot --interactive` for reliable element references when interacting with the page. Fall back to `get text body` or `get html body` if the page rejects JavaScript or returns `js_error`.

How do I avoid stale element references?

Re-snapshot after every significant action (click, fill, navigation) to refresh element refs. Follow the stable agent loop: verify URL → wait → snapshot → action → snapshot.

Can I save login state and reuse it?

Yes. After logging in, use `references/authentication.md#saving-authentication-state` to save the authenticated state, then load it in subsequent tasks to skip re-login.

What wait conditions are supported?

Load states (complete, domcontentloaded), selectors, text content, URL patterns, and custom JavaScript functions via `--function`.

Why does snapshot --interactive fail on some pages?

Complex pages may reject the JavaScript used for rich snapshots. Use `get url` to verify navigation, then fall back to `get text body` or `get html body` for content extraction.

Full instructions (SKILL.md)

Source of truth, from manaflow-ai/cmux.

name: cmux-browser description: 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.

Browser Automation with cmux

Use this skill for browser tasks inside cmux webviews.

Core Workflow

Open or target a browser surface.
Verify navigation with get url before waiting or snapshotting.
Snapshot (--interactive) to get fresh element refs.
Act with refs (click, fill, type, select, press).
Wait for state changes.
Re-snapshot after DOM/navigation changes.

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

Surface Targeting

# 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:

CLI output defaults to short refs (surface:N, pane:N, workspace:N, window:N).
UUIDs are still accepted on input; only request UUID output when needed (--id-format uuids|both).
Keep using one surface:N per task unless you intentionally switch.

Wait Support

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

Common Flows

Form Submit

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 "jane@example.com"
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

Clear an Input

cmux browser surface:7 fill e11 "" --snapshot-after --json
cmux browser surface:7 get value e11 --json

Stable Agent Loop (Recommended)

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

Deep-Dive References

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

Ready-to-Use Templates

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

Limits (WKWebView)

These commands currently return not_supported because they rely on Chrome/CDP-only APIs not exposed by WKWebView:

viewport emulation
offline emulation
trace/screencast recording
network route interception/mocking
low-level raw input injection

Use supported high-level commands (click, fill, press, scroll, wait, snapshot) instead.

Troubleshooting

`js_error` on `snapshot --interactive` or `eval`

Some 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

Use get url first so you know whether the page actually navigated.
Fall back to get text body or get html body when snapshot --interactive or eval returns js_error.
If the page is still failing, navigate to a simpler intermediate page, then retry the task from there.