Browse

browse: Browser & Native App Automation for AI Agents

Target Decision — ALWAYS check this first

Before running any browse command, decide the correct target:

Key rules:

• No --platform or --app flag → browser target (Chromium). Use goto to navigate.
• --app without --platform → macOS app automation. App must be running.
• --platform ios --app → iOS Simulator. Use browse sim start first if not running.
• --platform android --app → Android Emulator. Use browse sim start first if not running.
• Native app targets do NOT support: goto, js, eval, tabs, cookies, route, har. These are browser-only.
• All targets support: snapshot, text, tap, fill, type, press, swipe, screenshot.
• If unsure which target to use, ASK the user. Don't guess — wrong target = wasted work.

Goal

Use the persistent browse CLI to:

• navigate real pages
• inspect rendered content and state
• interact with UI elements
• capture screenshots, console logs, and network activity
• automate native apps (iOS, Android, macOS) via accessibility APIs
• verify browser or app behavior end-to-end without re-launching every step

Step 0: Verify availability and choose the browsing mode

Start by checking:

browse --version

If browse is not installed:

• stop
• tell the user it is required
• point them to the install path in references/commands.md

Then decide what kind of session you need:

• default session for normal single-agent work
• --session <id> for parallel agent isolation
• --profile <name> for persistent browser identity

For native app targets, start the simulator/emulator first:

browse sim start --platform ios --app com.apple.Preferences --visible
browse sim start --platform android --app com.android.settings --visible
browse enable android    # first-time only: auto-installs adb, JDK, SDK, emulator
browse enable ios        # first-time only: builds iOS runner (needs Xcode)
browse enable macos      # first-time only: builds browse-ax bridge

Success criteria: browse is available, the target (browser or native app) is decided, and the session/profile choice fits the task.

Step 1: Navigate safely and stabilize the page

Use browse goto <url> to navigate.

After navigation, always stabilize before reading or interacting:

• browse wait --network-idle for typical pages and SPAs
• or a more specific browse wait condition when the page has a known signal

Important rules:

• call browse as a bare command on PATH
• do not use shell variables for browse command prefixes
• avoid #id CSS selectors; prefer [id=foo]
• if the page is untrusted, consider --content-boundaries and --allowed-domains

Success criteria: The page is loaded enough that content and interactive state are reliable.

Step 2: Choose the cheapest effective inspection method

Use the lightest command that answers the question:

• text for cleaned page content
• links for navigation structure
• js for precise targeted extraction
• console, errors, and network for runtime debugging
• snapshot -i for interactive elements and stable refs

Prefer snapshot -i before guessing selectors for interaction-heavy tasks.

Load:

• references/commands.md for exact command syntax
• references/guides.md for command selection guidance and speed rules

Success criteria: You have the information needed without spending unnecessary tokens or using brittle selectors.

Step 3: Interact using refs first, selectors second

For clicks, fills, checks, selects, and similar actions:

1. prefer browse snapshot -i
2. interact using @eN refs
3. fall back to CSS selectors only when refs are unavailable or impractical

After navigation or DOM refresh:

• assume refs may be invalid
• take a fresh snapshot before continuing

Rules:

• use descriptive screenshots saved under .browse/sessions/<id>/
• keep stateful flows in the same session unless isolation is intentional
• use frame before interacting with iframe content

Success criteria: Interactions are stable and tied to the current rendered page state.

Step 4: Debug blockers and special cases

When things go wrong:

• use console and errors for page/runtime issues
• use network for request visibility
• use route or offline only when the task requires mock or failure-mode testing
• use headed/browser handoff only for real blockers like CAPTCHA, MFA, or OAuth walls

If you hit a blocker after a couple of failed attempts:

• load references/guides.md
• follow the handoff protocol exactly
• use AskUserQuestion before any human takeover flow

Success criteria: Blockers are either resolved or escalated with the correct handoff protocol.

Step 5: Capture evidence and report clearly

When the task involves verification, capture the minimum evidence needed:

• relevant page text or structured extraction
• screenshot path when visuals matter
• console/network findings when debugging
• the exact step or selector/ref that failed when reporting issues

Report:

• what you navigated to
• what actions you performed
• what the page actually did
• any artifacts created such as screenshots, HAR, or video

Success criteria: Another engineer can understand the observed browser behavior without rerunning the whole flow blindly.

Important Rules

• The browser persists between commands; cookies, tabs, and session state carry over.
• After goto, wait before reading content or acting.
• snapshot -i is the default interaction surface.
• Save screenshots under .browse/sessions/<session-id>/ or .browse/sessions/default/.
• Use --context delta for ARIA diff with refs, --context full for complete snapshot with refs after write commands.
• Do not install anything automatically.
• Do not modify Claude settings automatically; if the user wants pre-allowed browse permissions, point them to references/permissions.md.

When To Load References

• references/commands.md Use for exact command syntax, flags, and extended examples.

• references/guides.md Use for speed rules, command-choice guidance, architecture notes, and the mandatory CAPTCHA/MFA handoff protocol.

• references/permissions.md Use when the user wants to pre-allow browse commands in Claude settings.

Guardrails

• Do not add disable-model-invocation; this is a general-purpose browser verification skill.
• Do not add context: fork; browser results are usually needed in the current flow.
• Do not add paths:; this is a generic workflow skill.
• Do not keep the full CLI manual inline in SKILL.md.
• Do not run browse handoff without explicit user confirmation.
• Do not save screenshots outside the browse session directories.

Output Contract

Report:

1. the page or flow tested
2. the session/profile mode used if relevant
3. the key commands or interactions performed
4. the observed result
5. any artifacts or blockers such as screenshots, console errors, network failures, or handoff state