Browser Automation

Automate browser interactions using the browse CLI with Claude.

Setup check

Before running any browser commands, verify the CLI is available:

bash

which browse || npm install -g browse

Environment Selection (Local vs Remote)

The CLI supports explicit per-command environment flags. If you do nothing, the next session defaults to Browserbase when

BROWSERBASE_API_KEY

is set and to local otherwise.

Local mode

```
browse open <url> --local
```
starts a clean isolated local browser
```
browse open <url> --auto-connect
```
attaches to an already-running debuggable Chrome; use
```
--local
```
when no debuggable Chrome is available
```
browse open <url> --cdp <port|url>
```
attaches to a specific CDP target
Best for: development, localhost, trusted sites, and reproducible runs

Remote mode (Browserbase)

```
browse open <url> --remote
```
starts a Browserbase session
Without a local flag, Browserbase is also the default when
```
BROWSERBASE_API_KEY
```
is set
Provides: Browserbase Identity, Verified browsers, automatic CAPTCHA solving, residential proxies, session persistence
Use remote mode when: the target site has bot detection, CAPTCHAs, IP rate limiting, Cloudflare protection, or requires geo-specific access
Get credentials at https://browserbase.com/settings

When to choose which

Repeatable local testing / clean state:
```
browse open <url> --local
```
Reuse your local login/cookies:
```
browse open <url> --auto-connect
```
Simple browsing (docs, wikis, public APIs): local mode is fine
Protected sites (login walls, CAPTCHAs, anti-scraping): use remote mode
If local mode fails with bot detection or access denied: switch to remote mode

Commands

Most driver commands work across local, remote, and CDP sessions after the daemon starts.

Navigation

bash

browse open <url>                        # Go to URL
browse open <url> --local                # Go to URL in a clean local browser
browse open <url> --remote               # Go to URL in a Browserbase session
browse reload                            # Reload current page
browse back                              # Go back in history
browse forward                           # Go forward in history

Page state (prefer snapshot over screenshot)

bash

browse snapshot                          # Get accessibility tree with element refs (fast, structured)
browse screenshot --path <path>          # Take visual screenshot (slow, uses vision tokens)
browse get url                           # Get current URL
browse get title                         # Get page title
browse get text <selector>               # Get text content (use "body" for all text)
browse get html <selector>               # Get HTML content of element
browse get value <selector>              # Get form field value

Use

browse snapshot

as your default for understanding page state — it returns the accessibility tree with element refs you can use to interact. Only use

browse screenshot

when you need visual context (layout, images, debugging).

Interaction

bash

browse click <ref>                       # Click element by ref from snapshot (e.g., @0-5)
browse type <text>                       # Type text into focused element
browse fill <selector> <value>           # Fill input; add --press-enter if Enter is needed
browse select <selector> <values...>     # Select dropdown option(s)
browse press <key>                       # Press key (Enter, Tab, Escape, Cmd+A, etc.)
browse mouse drag <fromX> <fromY> <toX> <toY>  # Drag from one point to another
browse mouse scroll <x> <y> <deltaX> <deltaY>  # Scroll at coordinates
browse highlight <selector>              # Highlight element on page
browse is visible <selector>             # Check if element is visible
browse is checked <selector>             # Check if element is checked
browse wait <type> [arg]                 # Wait for: load, selector, timeout

Session management

bash

browse stop                              # Stop the browser daemon
browse status                            # Check daemon status and resolved mode
browse tab list                          # List all open tabs
browse tab switch <index-or-target-id>   # Switch to tab by index or target ID
browse tab close [index-or-target-id]    # Close tab

Typical workflow

If the environment matters, put

--local

--remote

--auto-connect

, or

--cdp <port|url>

on the first browser command.

browse open <url> --local

browse open <url> --remote

— navigate to the page

```
browse snapshot
```
— read the accessibility tree to understand page structure and get element refs

browse click <ref>

browse type <text>

browse fill <selector> <value>

— interact using refs from snapshot

```
browse snapshot
```
— confirm the action worked
Repeat 3-4 as needed
```
browse stop
```
— close the browser when done

Quick Example

bash

browse open https://example.com
browse snapshot                          # see page structure + element refs
browse click @0-5                        # click element with ref 0-5
browse get title
browse stop

Mode Comparison

Feature	Local	Browserbase
Speed	Faster	Slightly slower
Setup	Chrome required	API key required
Reuse existing local cookies	With `browse open <url> --auto-connect`	N/A
Verified browser	No	Yes (Browserbase Verified browser via Identity)
CAPTCHA solving	No	Yes (automatic reCAPTCHA/hCaptcha)
Residential proxies	No	Yes (201 countries, geo-targeting)
Session persistence	No	Yes (cookies/auth persist via contexts)
Best for	Development/simple pages	Protected sites, Browserbase Identity + Verified access, production scraping

Best Practices

Choose the local strategy deliberately: use
```
browse open <url> --local
```
for clean state,
```
browse open <url> --auto-connect
```
for existing local credentials, and
```
browse open <url> --remote
```
for protected sites
Always
browse open
first before interacting
Use
browse snapshot
to check page state — it's fast and gives you element refs
Only screenshot when visual context is needed (layout checks, images, debugging)
Use refs from snapshot to click/interact — e.g.,
```
browse click @0-5
```
browse stop
when done to clean up the browser session and clear the env override

Troubleshooting

"No active page": Run
```
browse stop
```
, then check
```
browse status
```
. If it still says running, kill the zombie daemon with
```
pkill -f "browse.*daemon"
```
, then retry
```
browse open
```
Chrome not found: Install Chrome, use
```
browse open <url> --auto-connect
```
if you already have a debuggable Chrome running, or switch to
```
browse open <url> --remote
```
Action fails: Run
```
browse snapshot
```
to see available elements and their refs
Browserbase fails: Verify API key is set

Switching to Remote Mode

Switch to remote when you detect: CAPTCHAs (reCAPTCHA, hCaptcha, Turnstile), bot detection pages ("Checking your browser..."), HTTP 403/429, empty pages on sites that should have content, or the user asks for it.

Don't switch for simple sites (docs, wikis, public APIs, localhost).

bash

browse open <url> --local          # clean isolated local browser
browse open <url> --auto-connect   # attach to existing debuggable Chrome
browse open <url> --remote         # Browserbase session

Mode flags are applied when a session starts. After

browse stop

, the next start falls back to env-var-based auto detection. Use

browse status

to inspect the resolved mode and target while the daemon is running.

For detailed examples, see EXAMPLES.md. For API reference, see REFERENCE.md.

browser

NPX Install

Tags

SKILL.md Content

Browser Automation

Setup check

Environment Selection (Local vs Remote)

Local mode

Remote mode (Browserbase)

When to choose which

Commands

Navigation

Page state (prefer snapshot over screenshot)

Interaction

Session management

Typical workflow

Quick Example

Mode Comparison

Best Practices

Troubleshooting

Switching to Remote Mode