Browser Automation

Automate browser interactions using the browse CLI with Claude.

Setup check

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

CODEBLOCK0

Environment Selection (Local vs Remote)

The CLI automatically selects between local and remote browser environments based on available configuration:

Local mode (default)

• - Uses local Chrome — no API keys needed
• Best for: development, simple pages, trusted sites with no bot protection

Remote mode (Browserbase)

• - Activated when BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are set
• Provides: anti-bot stealth, 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

• - 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

All commands work identically in both modes. The daemon auto-starts on first command.

Navigation

CODEBLOCK1

Page state (prefer snapshot over screenshot)

CODEBLOCK2

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

CODEBLOCK3

Session management

CODEBLOCK4

Typical workflow

1. 1. browse open <url> — navigate to the page
2. INLINECODE5 — read the accessibility tree to understand page structure and get element refs
3. INLINECODE6 / browse type <text> / browse fill <selector> <value> — interact using refs from snapshot
4. INLINECODE9 — confirm the action worked
5. Repeat 3-4 as needed
6. INLINECODE10 — close the browser when done

Quick Example

CODEBLOCK5

Mode Comparison

Feature	Local	Browserbase
Speed	Faster	Slightly slower
Setup

Chrome required | API key required | | Stealth mode | No | Yes (custom Chromium, anti-bot fingerprinting) | | CAPTCHA solving | No | Yes (automatic reCAPTCHA/hCaptcha) | | Residential proxies | No | Yes (201 countries, geo-targeting) | | Session persistence | No | Yes (cookies/auth persist across sessions) | | Best for | Development/simple pages | Protected sites, bot detection, production scraping |

Best Practices

1. 1. Always browse open first before interacting
2. Use browse snapshot to check page state — it's fast and gives you element refs
3. Only screenshot when visual context is needed (layout checks, images, debugging)
4. Use refs from snapshot to click/interact — e.g., INLINECODE13
5. browse stop when done to clean up the browser session

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 INLINECODE18
• Chrome not found: Install Chrome or use INLINECODE19
• Action fails: Run browse snapshot to see available elements and their refs
• Browserbase fails: Verify API key and project ID are 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).

CODEBLOCK6

The switch is sticky until you run browse stop or switch again.

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