browse: Browser & Native App Automation for AI Agents
Target Decision — ALWAYS check this first
Before running any browse command, decide the correct target:
| User wants to... |
Target |
Command pattern |
| Open a URL, test a website, scrape web content |
Browser (default) |
browse goto <url> |
Test a local dev server (localhost) |
Browser |
browse goto http://localhost:3000 |
| Browse a site that blocks bots (Cloudflare, Turnstile) |
Camoufox |
browse --runtime camoufox --headed goto <url> |
| Browse with a specific camoufox fingerprint profile |
Camoufox |
browse --runtime camoufox --camoufox-profile <name> --headed goto <url> |
| Search Google, YouTube, Amazon, etc. |
Browser |
browse goto @google "query" |
| Interact with an iOS app (Settings, Safari, custom app) |
iOS Simulator |
browse --platform ios --app <bundleId> <cmd> |
| Interact with an Android app (Settings, Chrome, custom app) |
Android Emulator |
browse --platform android --app <package> <cmd> |
| Interact with a macOS desktop app (System Settings, TextEdit) |
macOS App |
browse --app <name> <cmd> |
| Install and test an iOS .app or .ipa file |
iOS Simulator |
browse sim start --platform ios --app ./MyApp.app --visible |
| Install and test an Android .apk file |
Android Emulator |
browse sim start --platform android --app ./app.apk --visible |
Key rules:
- No
--platform or --app flag → browser target (Chromium). Use goto to navigate.
--runtime camoufox --headed → anti-detection Firefox. Use when site blocks normal browsing. See /browse-stealth skill for Turnstile/CAPTCHA bypass patterns.
@macro in goto URL → search macro expansion. browse goto @google "query" expands to Google search URL. 14 macros: @google, @youtube, @amazon, @reddit, @wikipedia, @twitter, @yelp, @spotify, @netflix, @linkedin, @instagram, @tiktok, @twitch, @reddit_subreddit.
--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 a site blocks you, switch to
--runtime camoufox --headed. If still blocked, use /browse-stealth for the full Turnstile bypass pattern.
- 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:
- prefer
browse snapshot -i
- interact using
@eN refs
- 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.
Runtime Selection
By default, browse uses Chromium via Playwright. Alternative runtimes:
| Runtime |
Engine |
Use case |
Install |
playwright (default) |
Chromium |
General browsing, testing |
Included |
camoufox |
Firefox (anti-detection) |
Sites with bot detection |
npm install camoufox-js && npx camoufox-js fetch |
rebrowser |
Chromium (stealth) |
Alternative stealth approach |
npm install rebrowser-playwright |
lightpanda |
Lightpanda |
Fast headless rendering |
See lightpanda.io |
chrome |
System Chrome |
Use real Chrome with extensions |
Chrome must be installed |
browse --runtime camoufox --headed goto https://protected-site.com
BROWSE_RUNTIME=camoufox browse goto https://example.com
New Features
Search Macros
browse goto @google "best coffee beans" # Google search
browse goto @youtube "tutorial" # YouTube search
browse goto @amazon "laptop" # Amazon search
browse goto @reddit "programming" # Reddit search
All macros: @google, @youtube, @amazon, @reddit, @reddit_subreddit, @wikipedia, @twitter, @yelp, @spotify, @netflix, @linkedin, @instagram, @tiktok, @twitch
Safety Flags (opt-in features)
| Flag |
Default |
What it does |
BROWSE_CONSENT_DISMISS=1 |
OFF |
Auto-dismiss cookie banners after navigation |
BROWSE_CLICK_FORCE=1 or --force |
OFF |
Force-click through overlay interception |
BROWSE_READINESS=1 or --ready |
OFF |
Wait for hydration after goto |
BROWSE_SERP_FASTPATH=1 or --serp |
OFF |
Google SERP DOM extraction (fast, no refs) |
BROWSE_COMMAND_LOCK=0 |
ON |
Disable per-session command serialization |
BROWSE_CAMOUFOX_PROFILE=<name> |
OFF |
Use a named camoufox profile (.browse/camoufox-profiles/<name>.json) |
New Commands
| Command |
Description |
images [sel] [--limit N] [--inline] |
List page images with src/alt/dimensions |
youtube-transcript <url> [--lang en] |
Extract YouTube captions via yt-dlp or browser |
schema |
Extract JSON-LD, Microdata, RDFa structured data (parsed JSON) |
meta |
Extract page meta tags (title, description, canonical, OG, Twitter, hreflang, robots, viewport) |
headings |
Extract H1-H6 heading hierarchy with counts and indented tree |
profiles |
List available camoufox profiles from .browse/camoufox-profiles/ |
Snapshot Windowing
Large snapshots (>80K chars) are automatically paginated:
browse snapshot -i # first page
browse snapshot -i --offset 500 # next page (line offset from previous output)
Output Contract
Report:
- the page or flow tested
- the session/profile mode used if relevant
- the key commands or interactions performed
- the observed result
- any artifacts or blockers such as screenshots, console errors, network failures, or handoff state
1---
2name: browse
3version: 4.0.0
4description: |
5 Drive a REAL browser and native apps the way a user would — not fetch raw HTML — through the
6 persistent `browse` CLI: one long-lived headless Chromium (plus iOS, Android, and macOS apps via
7 accessibility APIs) where goto, snapshot, click, fill, JavaScript, and screenshot share session
8 state at ~100ms/command and interaction rides stable @eN refs, not brittle selectors. Use when
9 verifying, navigating, or automating live web or app behavior beyond what code-reading or a raw
10 fetch reveals.
11allowed-tools:
12 - AskUserQuestion
13 - Bash
14 - Read
15argument-hint: "[URL, page flow, or web verification task]"
16arguments:
17 - request
18when_to_use: |
19 Use when the task needs live browser or app behavior — navigation, UI interaction, form flows, or
20 rendered-page/console/network inspection. Examples: "test this local page", "click through this
21 flow", "verify the login", "inspect console errors". Do NOT use for pure HTTP fetching, when a site
22 blocks you and needs anti-detection (browse-stealth), or for the specialized audits (browse-seo /
23 browse-aeo / browse-geo) and QA-flow capture (browse-qa); this is the general driver they build on.
24effort: high
25metadata:
26 source: https://skillmd.com/skills/ulpi-io/browse
27---
28
29# browse: Browser & Native App Automation for AI Agents
30
31## Target Decision — ALWAYS check this first
32
33Before running any browse command, decide the correct target:
34
35| User wants to... | Target | Command pattern |
36|---|---|---|
37| Open a URL, test a website, scrape web content | **Browser** (default) | `browse goto <url>` |
38| Test a local dev server (`localhost`) | **Browser** | `browse goto http://localhost:3000` |
39| Browse a site that blocks bots (Cloudflare, Turnstile) | **Camoufox** | `browse --runtime camoufox --headed goto <url>` |
40| Browse with a specific camoufox fingerprint profile | **Camoufox** | `browse --runtime camoufox --camoufox-profile <name> --headed goto <url>` |
41| Search Google, YouTube, Amazon, etc. | **Browser** | `browse goto @google "query"` |
42| Interact with an iOS app (Settings, Safari, custom app) | **iOS Simulator** | `browse --platform ios --app <bundleId> <cmd>` |
43| Interact with an Android app (Settings, Chrome, custom app) | **Android Emulator** | `browse --platform android --app <package> <cmd>` |
44| Interact with a macOS desktop app (System Settings, TextEdit) | **macOS App** | `browse --app <name> <cmd>` |
45| Install and test an iOS .app or .ipa file | **iOS Simulator** | `browse sim start --platform ios --app ./MyApp.app --visible` |
46| Install and test an Android .apk file | **Android Emulator** | `browse sim start --platform android --app ./app.apk --visible` |
47
48**Key rules:**
49- **No `--platform` or `--app` flag** → browser target (Chromium). Use `goto` to navigate.
50- **`--runtime camoufox --headed`** → anti-detection Firefox. Use when site blocks normal browsing. See `/browse-stealth` skill for Turnstile/CAPTCHA bypass patterns.
51- **`@macro` in goto URL** → search macro expansion. `browse goto @google "query"` expands to Google search URL. 14 macros: @google, @youtube, @amazon, @reddit, @wikipedia, @twitter, @yelp, @spotify, @netflix, @linkedin, @instagram, @tiktok, @twitch, @reddit_subreddit.
52- **`--app` without `--platform`** → macOS app automation. App must be running.
53- **`--platform ios --app`** → iOS Simulator. Use `browse sim start` first if not running.
54- **`--platform android --app`** → Android Emulator. Use `browse sim start` first if not running.
55- **Native app targets do NOT support**: `goto`, `js`, `eval`, `tabs`, `cookies`, `route`, `har`. These are browser-only.
56- **All targets support**: `snapshot`, `text`, `tap`, `fill`, `type`, `press`, `swipe`, `screenshot`.
57- **If a site blocks you**, switch to `--runtime camoufox --headed`. If still blocked, use `/browse-stealth` for the full Turnstile bypass pattern.
58- **If unsure which target to use, ASK the user.** Don't guess — wrong target = wasted work.
59
60## Goal
61
62Use the persistent `browse` CLI to:
63
64- navigate real pages
65- inspect rendered content and state
66- interact with UI elements
67- capture screenshots, console logs, and network activity
68- automate native apps (iOS, Android, macOS) via accessibility APIs
69- verify browser or app behavior end-to-end without re-launching every step
70
71## Step 0: Verify availability and choose the browsing mode
72
73Start by checking:
74
75```bash
76browse --version
77```
78
79If `browse` is not installed:
80
81- stop
82- tell the user it is required
83- point them to the install path in `references/commands.md`
84
85Then decide what kind of session you need:
86
87- default session for normal single-agent work
88- `--session <id>` for parallel agent isolation
89- `--profile <name>` for persistent browser identity
90
91For native app targets, start the simulator/emulator first:
92
93```bash
94browse sim start --platform ios --app com.apple.Preferences --visible
95browse sim start --platform android --app com.android.settings --visible
96browse enable android # first-time only: auto-installs adb, JDK, SDK, emulator
97browse enable ios # first-time only: builds iOS runner (needs Xcode)
98browse enable macos # first-time only: builds browse-ax bridge
99```
100
101**Success criteria**: `browse` is available, the target (browser or native app) is decided, and the session/profile choice fits the task.
102
103## Step 1: Navigate safely and stabilize the page
104
105Use `browse goto <url>` to navigate.
106
107After navigation, always stabilize before reading or interacting:
108
109- `browse wait --network-idle` for typical pages and SPAs
110- or a more specific `browse wait` condition when the page has a known signal
111
112Important rules:
113
114- call `browse` as a bare command on PATH
115- do not use shell variables for browse command prefixes
116- avoid `#id` CSS selectors; prefer `[id=foo]`
117- if the page is untrusted, consider `--content-boundaries` and `--allowed-domains`
118
119**Success criteria**: The page is loaded enough that content and interactive state are reliable.
120
121## Step 2: Choose the cheapest effective inspection method
122
123Use the lightest command that answers the question:
124
125- `text` for cleaned page content
126- `links` for navigation structure
127- `js` for precise targeted extraction
128- `console`, `errors`, and `network` for runtime debugging
129- `snapshot -i` for interactive elements and stable refs
130
131Prefer `snapshot -i` before guessing selectors for interaction-heavy tasks.
132
133Load:
134
135- `references/commands.md` for exact command syntax
136- `references/guides.md` for command selection guidance and speed rules
137
138**Success criteria**: You have the information needed without spending unnecessary tokens or using brittle selectors.
139
140## Step 3: Interact using refs first, selectors second
141
142For clicks, fills, checks, selects, and similar actions:
143
1441. prefer `browse snapshot -i`
1452. interact using `@eN` refs
1463. fall back to CSS selectors only when refs are unavailable or impractical
147
148After navigation or DOM refresh:
149
150- assume refs may be invalid
151- take a fresh snapshot before continuing
152
153Rules:
154
155- use descriptive screenshots saved under `.browse/sessions/<id>/`
156- keep stateful flows in the same session unless isolation is intentional
157- use `frame` before interacting with iframe content
158
159**Success criteria**: Interactions are stable and tied to the current rendered page state.
160
161## Step 4: Debug blockers and special cases
162
163When things go wrong:
164
165- use `console` and `errors` for page/runtime issues
166- use `network` for request visibility
167- use `route` or `offline` only when the task requires mock or failure-mode testing
168- use headed/browser handoff only for real blockers like CAPTCHA, MFA, or OAuth walls
169
170If you hit a blocker after a couple of failed attempts:
171
172- load `references/guides.md`
173- follow the handoff protocol exactly
174- use `AskUserQuestion` before any human takeover flow
175
176**Success criteria**: Blockers are either resolved or escalated with the correct handoff protocol.
177
178## Step 5: Capture evidence and report clearly
179
180When the task involves verification, capture the minimum evidence needed:
181
182- relevant page text or structured extraction
183- screenshot path when visuals matter
184- console/network findings when debugging
185- the exact step or selector/ref that failed when reporting issues
186
187Report:
188
189- what you navigated to
190- what actions you performed
191- what the page actually did
192- any artifacts created such as screenshots, HAR, or video
193
194**Success criteria**: Another engineer can understand the observed browser behavior without rerunning the whole flow blindly.
195
196## Important Rules
197
198- The browser persists between commands; cookies, tabs, and session state carry over.
199- After `goto`, wait before reading content or acting.
200- `snapshot -i` is the default interaction surface.
201- Save screenshots under `.browse/sessions/<session-id>/` or `.browse/sessions/default/`.
202- Use `--context delta` for ARIA diff with refs, `--context full` for complete snapshot with refs after write commands.
203- Do not install anything automatically.
204- Do not modify Claude settings automatically; if the user wants pre-allowed browse permissions, point them to `references/permissions.md`.
205
206## When To Load References
207
208- `references/commands.md`
209 Use for exact command syntax, flags, and extended examples.
210
211- `references/guides.md`
212 Use for speed rules, command-choice guidance, architecture notes, and the mandatory CAPTCHA/MFA handoff protocol.
213
214- `references/permissions.md`
215 Use when the user wants to pre-allow browse commands in Claude settings.
216
217## Guardrails
218
219- Do not add `disable-model-invocation`; this is a general-purpose browser verification skill.
220- Do not add `context: fork`; browser results are usually needed in the current flow.
221- Do not add `paths:`; this is a generic workflow skill.
222- Do not keep the full CLI manual inline in `SKILL.md`.
223- Do not run `browse handoff` without explicit user confirmation.
224- Do not save screenshots outside the browse session directories.
225
226## Runtime Selection
227
228By default, browse uses Chromium via Playwright. Alternative runtimes:
229
230| Runtime | Engine | Use case | Install |
231|---------|--------|----------|---------|
232| `playwright` (default) | Chromium | General browsing, testing | Included |
233| `camoufox` | Firefox (anti-detection) | Sites with bot detection | `npm install camoufox-js && npx camoufox-js fetch` |
234| `rebrowser` | Chromium (stealth) | Alternative stealth approach | `npm install rebrowser-playwright` |
235| `lightpanda` | Lightpanda | Fast headless rendering | See lightpanda.io |
236| `chrome` | System Chrome | Use real Chrome with extensions | Chrome must be installed |
237
238```bash
239browse --runtime camoufox --headed goto https://protected-site.com
240BROWSE_RUNTIME=camoufox browse goto https://example.com
241```
242
243## New Features
244
245### Search Macros
246```bash
247browse goto @google "best coffee beans" # Google search
248browse goto @youtube "tutorial" # YouTube search
249browse goto @amazon "laptop" # Amazon search
250browse goto @reddit "programming" # Reddit search
251```
252
253All macros: @google, @youtube, @amazon, @reddit, @reddit_subreddit, @wikipedia, @twitter, @yelp, @spotify, @netflix, @linkedin, @instagram, @tiktok, @twitch
254
255### Safety Flags (opt-in features)
256| Flag | Default | What it does |
257|------|---------|-------------|
258| `BROWSE_CONSENT_DISMISS=1` | OFF | Auto-dismiss cookie banners after navigation |
259| `BROWSE_CLICK_FORCE=1` or `--force` | OFF | Force-click through overlay interception |
260| `BROWSE_READINESS=1` or `--ready` | OFF | Wait for hydration after goto |
261| `BROWSE_SERP_FASTPATH=1` or `--serp` | OFF | Google SERP DOM extraction (fast, no refs) |
262| `BROWSE_COMMAND_LOCK=0` | ON | Disable per-session command serialization |
263| `BROWSE_CAMOUFOX_PROFILE=<name>` | OFF | Use a named camoufox profile (`.browse/camoufox-profiles/<name>.json`) |
264
265### New Commands
266| Command | Description |
267|---------|------------|
268| `images [sel] [--limit N] [--inline]` | List page images with src/alt/dimensions |
269| `youtube-transcript <url> [--lang en]` | Extract YouTube captions via yt-dlp or browser |
270| `schema` | Extract JSON-LD, Microdata, RDFa structured data (parsed JSON) |
271| `meta` | Extract page meta tags (title, description, canonical, OG, Twitter, hreflang, robots, viewport) |
272| `headings` | Extract H1-H6 heading hierarchy with counts and indented tree |
273| `profiles` | List available camoufox profiles from `.browse/camoufox-profiles/` |
274
275### Snapshot Windowing
276Large snapshots (>80K chars) are automatically paginated:
277```bash
278browse snapshot -i # first page
279browse snapshot -i --offset 500 # next page (line offset from previous output)
280```
281
282## Output Contract
283
284Report:
285
2861. the page or flow tested
2872. the session/profile mode used if relevant
2883. the key commands or interactions performed
2894. the observed result
2905. any artifacts or blockers such as screenshots, console errors, network failures, or handoff state