skilld
All skills
manaflow-ai avatar

/cmux-browser

@f97f1e9
by manaflow-aimanaflow-ai/cmux28k stars
2,423

End-user browser automation with cmux. Use when you need to open sites, inspect or interact with browser surfaces, wait for page state, and extract data without stealing focus.

Ask your Agent

Use this Skill: https://skilld.dev/gh/manaflow-ai/cmux/cmux-browser

This session only. Nothing lands on disk.

referencescommands.md

≈2.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Command Reference (cmux Browser)

Surface contract

Run cmux browser --help against the installed binary before relying on exact syntax. Creation verbs (open, open-split, new) and the explicitly global browser verbs listed in SKILL.md may omit a surface. Every surface-bound command that reads or mutates an existing browser must include one:

cmux browser --surface <surface> get url
cmux browser --surface <surface> snapshot --interactive
cmux browser --surface <surface> tab list
cmux browser --surface <surface> click <selector-or-ref>

cmux browser <surface> <verb> ... is the equivalent positional form. See surface-discovery.md before targeting an existing authenticated browser or a browser in another workspace.

Accepted aliases

Use the preferred column in new docs/scripts; every alias still requires the same explicit surface.

Purpose Preferred Accepted alias
Read URL cmux browser --surface <surface> get url cmux browser --surface <surface> url or get-url
Navigate cmux browser --surface <surface> goto <url> navigate
Interactive snapshot cmux browser --surface <surface> snapshot --interactive -i
Press a key cmux browser --surface <surface> press <key> key

The upstream agent-browser command's implicit page context maps to an explicit cmux surface. Its interactive snapshot maps to snapshot --interactive; its open command maps to cmux browser open because creation returns a new surface.

Discovery and creation

cmux identify --json
cmux tree --all --json
cmux browser --surface <surface> identify --json

cmux --json browser open <url> --focus false
cmux --json browser open <url> --workspace <workspace> --window <window> --focus false
cmux --json browser open-split <url> --workspace <workspace> --focus false

Creation defaults to the caller's CMUX_WORKSPACE_ID when neither --workspace nor --window is supplied, and --focus defaults to false. An explicit --workspace lets an agent create in another workspace without selecting it.

Navigation

cmux browser --surface <surface> goto <url>
cmux browser --surface <surface> back|forward|reload
cmux browser --surface <surface> get url|title

Snapshot and inspection

cmux browser --surface <surface> snapshot --interactive
cmux browser --surface <surface> snapshot --interactive --compact --max-depth 3
cmux browser --surface <surface> get text body
cmux browser --surface <surface> get html body
cmux browser --surface <surface> get value "#email"
cmux browser --surface <surface> get attr "#email" --attr placeholder
cmux browser --surface <surface> get count ".row"
cmux browser --surface <surface> get box "#submit"
cmux browser --surface <surface> get styles "#submit" --property color
cmux browser --surface <surface> eval '<js>'

Interaction

cmux browser --surface <surface> click|dblclick|hover|focus <selector-or-ref>
cmux browser --surface <surface> fill <selector-or-ref> [text]
cmux browser --surface <surface> type <selector-or-ref> <text>
cmux browser --surface <surface> press|key|keydown|keyup [--key <key> | <key>]
cmux browser --surface <surface> select <selector-or-ref> <value>
cmux browser --surface <surface> check|uncheck <selector-or-ref>
cmux browser --surface <surface> scroll [--selector <css>] [--dx <n>] [--dy <n>]

Empty fill text clears the field. Keyboard names follow Playwright/W3C conventions (Enter, Tab, Escape, ArrowLeft, Space). Supported keys use the native WebKit input path, preserving browser defaults such as contenteditable caret movement, selection, scrolling, and control activation; opaque tokens use a page-event compatibility fallback. Space, Spacebar, and space emit DOM key " " with code "Space"; use --key ' ' to pass the raw DOM key. Use keydown Shift/keyup Shift (or another supported modifier) around an arrow press when a page editor should extend a selection; the modifier state is retained per browser surface.

Wait

cmux browser --surface <surface> wait --selector "#ready" --timeout-ms 10000
cmux browser --surface <surface> wait --text "Done" --timeout-ms 10000
cmux browser --surface <surface> wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser --surface <surface> wait --load-state complete --timeout-ms 15000
cmux browser --surface <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000

Design mode

cmux browser --surface <surface> design-mode enable|status|disable --json

Design mode lets a user select page elements and copy their DOM, style, URL, and screenshot context for pasting into an agent. CLI enable/disable never moves application focus or copies context automatically.

Session, state, and diagnostics

cmux browser --surface <surface> cookies get|set|clear ...
cmux browser --surface <surface> cookies clear --url https://app.example.com/
cmux browser --surface <surface> cookies clear --domain app.example.com
cmux browser --surface <surface> cookies clear --all
cmux browser --surface <surface> storage local|session get|set|clear ...
cmux browser --surface <surface> tab list|new|switch|close ...
cmux browser --surface <surface> state save|load <path>
cmux browser --surface <surface> console list|clear
cmux browser --surface <surface> errors list|clear
cmux browser --surface <surface> highlight <selector>
cmux browser --surface <surface> screenshot
cmux browser --surface <surface> download list [--limit <1...25>]
cmux browser --surface <surface> download wait --timeout-ms 10000

download list returns the newest records for that browser surface without consuming download wait events. JSON records include download_id, filename, the actual saved path (or null), status, bytes when known, and path_exists when a path is present. The list is capped at 25 records; --limit may request a smaller positive count. Text output marks unavailable values explicitly. The legacy positional form treats a bare token as a destination path, so use the explicit download wait <path> or download --path <path> spelling when you want to make that intent unambiguous. download list is the only listing subcommand.

cookies clear requires an explicit scope (--url, --domain, --name, --path, another cookie filter, or --all). URL scope follows cookie domain/path, secure, and expiration matching for the requested URL. JSON responses include the number of removed cookies as cleared.

Agent reliability

Use --snapshot-after on mutating actions to get a fresh post-action snapshot. Re-snapshot after navigation, modal open/close, or major DOM changes. Prefer short handles in output; use --id-format both only when a UUID must be logged or exported. If the handle is stale, rediscover it; never silently retarget the focused browser.

Viewport emulation

cmux browser --surface <surface> viewport 1280 720
cmux browser --surface <surface> screenshot --out /tmp/desktop.png
cmux browser --surface <surface> viewport reset

Dimensions are limited to 1..4096 CSS pixels. cmux changes window.innerWidth/window.innerHeight and aspect-fits the page inside the existing pane; it does not resize the pane, move other surfaces, or change focus. Screenshot PNG dimensions are exact CSS pixels on Retina and non-Retina displays.

An unsupported viewport/page-zoom combination leaves the viewport unchanged and returns invalid_params with reason viewport_zoom_render_geometry_too_large plus maximum_page_zoom. An attached browser inspector returns invalid_state with reason attached_browser_inspector; close or detach it first. Opening or redocking an attached inspector while emulation is active resets the viewport to native sizing.

Known WKWebView gaps (not_supported)

browser.geolocation.set, browser.offline.set, browser.trace.start|stop, browser.network.route|unroute|requests, browser.screencast.start|stop, and browser.input_mouse|input_keyboard|input_touch are not supported by the WKWebView engine.

See also snapshot-refs.md, authentication.md, and session-management.md.

Source: SKILL.md on GitHub

Third-party checks

1 alert16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill provides browser automation capabilities and correctly identifies the sensitivity of browser session data, providing best practices for securing it with restricted permissions and safe credential handling. It includes a mechanism for updates using an installer utility from the author's repository. The primary security consideration is the risk of indirect prompt injection inherent in processing content from arbitrary websites.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: MEDIUM · 1 issue

  • Runlayer6mo

    5/11 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at f97f1e9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

Topics

  • CLI
  • browser-automation
  • cmux
  • web-scraping
  • form-automation
  • wkwebview
  • macos

README badge

README badge for manaflow-ai/cmux

What it does

Automates browser interactions within cmux webviews by opening pages, waiting for state changes, snapshotting the DOM, and performing actions like clicks and form fills using element references. Use this for tasks like form submission, data extraction, and navigation verification in cmux surfaces.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with WKWebView, or only Chrome?
It uses WKWebView. Some Chrome/CDP-only features like viewport emulation, network mocking, and trace recording are not supported, but core actions (click, fill, press, scroll, wait, snapshot) work.
How do I handle authentication and preserve login state across browser tasks?
Use the authenticated-session template or follow the authentication reference guide, which covers login flows, OAuth, 2FA patterns, and the save/load state workflow to persist credentials between surfaces.
What should I do if snapshot --interactive fails with a js_error?
Fall back to get url, get text body, or get html body to verify page state. If the issue persists, navigate to a simpler intermediate page and retry the task from there.
Can I run multiple browser tasks in parallel or do I need one surface per task?
Keep one surface per task unless you intentionally switch. Multi-surface isolation and state persistence patterns are covered in the session-management reference.
Does this work with the agent-browser skill or are they separate workflows?
This skill is specific to cmux webviews. It uses cmux CLI commands and surface references; the wait patterns are similar to agent-browser but the execution model is distinct to cmux.

Generated from the current SKILL.md. These answers refresh after source changes.