cmux-browser

cmux browser

Mandatory Behavior

When this skill is activated:

• MUST use cmux browser commands via Bash tool for ALL web interactions
• MUST NOT use WebFetch, WebSearch, or any mcp__claude-in-chrome__* tools as substitutes
• If cmux browser fails after 3 attempts, report the error to the user instead of silently switching tools
• Sub-agents CAN and SHOULD use cmux browser — see Parallel Browsing section

Surface Model

Every session starts with open, which returns a surface ID. Use it in all subsequent commands.

cmux browser open https://example.com    # → OK surface=surface:7
cmux browser surface:7 <subcommand> [args] [flags]

Core Workflow

open → wait → snapshot/extract → interact → verify

Note: close subcommand is NOT supported. Surfaces are cleaned up automatically.

Task Recipes

Recipe 1: Read & Summarize a Web Page

# 1. Open — macOS-safe surface parse (BSD grep has no -P / \K)
SURFACE=$(cmux browser open https://example.com 2>&1 | grep -oE 'surface:[0-9]+' | head -1)

# 2. Wait for load (prefer --selector/--text when a specific element is needed)
cmux browser $SURFACE wait --load-state complete --timeout-ms 15000

# 3. Extract text — PREFER get text / get html over eval (see Known Limitations)
cmux browser $SURFACE get text "body"
cmux browser $SURFACE get text "main"      # or "article"
cmux browser $SURFACE get html "body"      # NOTE: get html REQUIRES a selector

For long pages, scroll and re-extract:

cmux browser $SURFACE get text "body"
cmux browser $SURFACE scroll --dy 2000
cmux browser $SURFACE get text "body"

Recipe 2: Extract Structured Data

Prefer DOM-access commands — they work even where eval is blocked (see Known Limitations).

cmux browser $SURFACE get attr "a.primary" --attr href
cmux browser $SURFACE get count ".list-item"     # may js_error on CSP sites → fall back to get html + parse
cmux browser $SURFACE get html "body"            # then parse with shell/python (grep, jq, BeautifulSoup)

# eval works on MOST sites, but FAILS with js_error on CSP-strict sites (e.g. Hacker News):
cmux browser $SURFACE eval "JSON.stringify(Array.from(document.querySelectorAll('h2')).map(h => h.textContent))"