browse-stealth

What this skill does

# browse-stealth: Stealth Web Automation for AI Agents

## Target Decision — ALWAYS check this first

Before running any browse-stealth command, confirm the target matches stealth's purpose:

| User wants to... | Target | Command pattern |
|---|---|---|
| Open a site behind Cloudflare/Turnstile | **Camoufox** | `browse --runtime camoufox --headed goto <url>` |
| Bypass Google "unusual traffic" block | **Camoufox** | `browse --runtime camoufox --camoufox-profile google --headed goto @google "query"` |
| Scrape a site that returns 403 or a challenge page | **Camoufox** | `browse --runtime camoufox --headed goto <url>` |
| Use a specific camoufox fingerprint or proxy profile | **Camoufox** | `browse --runtime camoufox --camoufox-profile <name> --headed goto <url>` |
| Stay logged in across stealth sessions | **Camoufox + browser profile** | `browse --runtime camoufox --camoufox-profile <n> --profile <p> --headed goto <url>` |
| Open a normal site that isn't blocked | **Default browser** | Use the `browse` skill, not this one |
| Interact with an iOS/Android/macOS app | **Native target** | Use the `browse` skill, not this one |

**Key rules:**
- **`--runtime camoufox`** selects the hardened Firefox engine with C++-level fingerprint spoofing.
- **`--headed`** is strongly recommended. Headless Firefox is easier to detect.
- **`--camoufox-profile <name>`** loads `.browse/camoufox-profiles/<name>.json`. Applied at server startup only — `browse stop` first if switching profiles.
- **`--profile <name>`** persists browser cookies/localStorage across restarts. Independent of `--camoufox-profile`.
- **Never mix `--profile` with `--session`.** `--profile` persists identity; `--session` isolates parallel agents in one server.
- **Stealth does not replace IP reputation.** Fingerprint spoofing alone will not bypass IP-based blocks. Use a residential proxy for heavily protected sites.
- **If the site loads fine without stealth, switch back to the `browse` skill.** Camoufox is slower.
- **If unsure which target to use, ASK the user.** Don't guess.

## Goal

Use the persistent `browse` CLI with the `camoufox` runtime to:

- navigate sites that block normal browsers
- pass Cloudflare Turnstile and similar anti-bot challenges
- inspect rendered content and state on protected pages
- interact with UI elements without tripping detection
- capture screenshots, console logs, and network activity
- maintain authenticated sessions across restarts
- rotate proxies and fingerprints per task

## Step 0: Verify availability and choose the stealth profile

Start by checking:

```bash
browse --version
browse --runtime camoufox doctor
```

If `browse` is not installed, stop and tell the user:

> Install it with: `npm install -g @ulpi/browse`

If camoufox is not installed, stop and tell the user:

> Install it with: `npm install camoufox-js && npx camoufox-js fetch`

Do NOT install anything automatically.

Then decide which stealth profile fits the task. Run `/browse-config` to generate one, or pick an existing preset:

| Preset | When to use |
|---|---|
| **stealth** | General anti-detection (geoip + humanize) |
| **google** | Google search, SERP scraping (geoip + humanize + random OS) |
| **scrape** | High-throughput scraping (blocks images, WebRTC, WebGL; enables cache) |
| **custom** | User walks through each option |

Then decide what kind of session you need:

- default session for normal single-agent work
- `--session <id>` for parallel agent isolation (same camoufox server)
- `--profile <name>` for persistent browser identity (cookies survive restarts)

**Success criteria**: `browse` + camoufox are available, a stealth profile is chosen, and the session/browser-profile choice fits the task.

## Step 1: Navigate safely and stabilize the page

Stop any running server (required if switching `--camoufox-profile`), then launch:

```bash
browse stop
browse --runtime camoufox --camoufox-profile <name> --headed goto <url>
```

If no named profile exists, the `camoufox` section in `browse.json` is used automatically:

```bash
browse stop
browse --runtime camoufox --headed goto <url>
```

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]`
- always pass `--runtime camoufox` on follow-up commands, or set `BROWSE_RUNTIME=camoufox` in the environment
- `BROWSE_CONSENT_DISMISS=1` auto-dismisses cookie banners (useful for EU locales)

**Success criteria**: The protected page is loaded, the challenge (if any) is settled, and content is 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
- `--serp` on Google for SERP-structured extraction without refs

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

Load:

- `/browse` references for full command syntax (`references/commands.md` in the `browse` skill)
- `/browse` references for speed rules (`references/guides.md`)

**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 --runtime camoufox snapshot -i`
2. interact using `@eN` refs
3. fall back to CSS selectors only when refs are unavailable

After navigation or DOM refresh:

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

Rules:

- enable `humanize: true` (or a higher number like `1.5`–`2.0`) in the profile for human-like delays
- 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 (Turnstile lives in an iframe)

**Success criteria**: Interactions are stable, undetected, 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 (look for challenge endpoints)
- check for iframes with `challenges.cloudflare.com` in their src (Turnstile)
- check for text like "unusual traffic" or "verify you are human"

Stealth-specific escalation path when a site still blocks you:

1. raise `humanize` in the camoufox profile (try `1.5` or `2.0`)
2. switch OS fingerprint (`os: ["windows", "macos", "linux"]` for random selection)
3. add a residential proxy to the profile and `browse stop` + relaunch
4. use `--headed` if you were running headless
5. as a last resort, hand off to the user via `browse handoff` — ask first with `AskUserQuestion`

If the site loads fine at some point, switch back to the default `browse` skill for the rest of the task.

**Success criteria**: Blockers are either resolved within the stealth runtime 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
- the camoufox profile and proxy used, if relevant to reproducibility

Report:

- what you navigated to
- which camoufox profile and browser profile were used
- what actions you performed
- what the page actually did (including any detected challenges)
- any artifacts created such as screenshots, HAR, or video