// 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.
Guide and apply cmux keyboard shortcut customization. Use when the user asks to customize, rebind, unbind, reset, audit, or create shortcut templates for cmux, including tmux-style, Vim-style, terminal-first, browser-heavy, iTerm/Terminal-like, or agent-triage layouts.
View and edit cmux settings in ~/.config/cmux/cmux.json. Use when the user wants to change cmux preferences (appearance, sidebar, notifications, automation, browser, shortcuts), set a value by JSON path, validate the file, open it in an editor, or look up which keys cmux recognizes. Triggers on '/cmux-settings', 'change cmux setting', 'set <something> in cmux', 'cmux config', 'cmux.json', or 'rebind a cmux shortcut'.
Customize cmux for an end user. Use when changing cmux.json actions, custom commands, workspace layouts, plus-button behavior, surface tab bar buttons, Command Palette entries, Dock controls, sidebar and app settings, shortcuts, notifications, browser routing, examples-library presets, or Ghostty-backed terminal preferences.
Run end-user cmux diagnostics. Use when cmux hooks, notifications, session restore, settings, browser automation, socket access, CLI control, or agent resume behavior is not working, or when the user asks for a cmux health check, doctor report, or support-safe debug summary.
Work inside the current cmux workspace and terminal. Use for cmux workspace, current workspace, caller surface, panes, surfaces, socket targeting, and non-interfering cmux automation.
Open markdown files in a formatted viewer panel with live reload. Use when you need to display plans, documentation, or notes alongside the terminal with rich rendering (headings, code blocks, tables, lists).
| 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. |
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 "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
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.