Browser Automation

CrabCode supports the default built-in browser backend (crabcode-browser) and the real-Chrome extension backend: navigate, click, read console, screenshot, and inspect network traffic.

What it is

CrabCode browser automation is not a single Chrome-extension feature. It has two independent backends:

Mode	Browser used	Connection	Best for
Built-in browser mode (default)	Standalone local Chromium (spawned by `crabcode-browser`)	`crabcode-browser` native daemon	Automation scripts, CI, isolated sessions, regular frontend debugging
Extension mode	Your day-to-day Chrome	`CrabCode in Chrome` extension + native host	Real logged-in accounts, OAuth/SSO, intranet pages, pages that must use your Chrome session

The default backend is crabcode-browser — a native daemon (an Apache-2.0 fork of agent-browser) that drives an isolated Chromium session. The desktop release bundles the executable; first use auto-downloads Chrome for Testing (or reuses a locally installed Chrome). The playwright-cli backend mentioned in older docs has been removed. The model and the desktop Browser Automation page default to built-in browser mode. Use extension mode only when the user explicitly asks for their real Chrome, the task requires login state/OAuth/SSO, or the built-in backend cannot reach the page.

The two backends do not share context: cookies, login state, local storage, download directories, and extension permissions are all separate. CrabCode does not silently switch between them; when a switch is needed, the desktop app shows a clear CTA and the user decides.

When you see this doc

The /chrome onboarding or status screen in the TUI
The help entry in the desktop Browser Automation page
Extension-mode setup, reconnect, or troubleshooting flows

Built-in browser mode: the default

Built-in browser mode talks to the crabcode-browser daemon through crabcode browser ... and launches an isolated Chromium profile. It does not require the Chrome extension and does not read your day-to-day Chrome login state.

Typical flow:

bash

crabcode browser status --json      # reports "backend":"crabcode-browser"
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full --profile dev
crabcode browser stop --profile dev
crabcode browser status --json      # reports "backend":"crabcode-browser"
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full --profile dev
crabcode browser stop --profile dev

Common capabilities include:

Session and profiles: status, start, stop, profiles, create-profile, delete-profile, reset-profile
Tabs and navigation: tabs, open, focus, close, navigate, back, forward, reload
Inspection: DOM snapshot (element refs are @eN), screenshot, pdf, console, errors, requests (with --filter <regex>, --clear, --static)
Actions: click, type, press, hover, scrollintoview, drag, select, fill, upload, dialog, wait, evaluate, highlight
Storage and artifacts: cookies, storage, download, waitfordownload, trace, set (offline / headers / credentials / geolocation / media / device)

Network reads are id-based, single command: run crabcode browser requests --json [--filter <regex>] to list captured requests and pick an id, then crabcode browser network request <id> to get the combined request + response detail (headers + body) in one call. There is no per-index headers/body command; the legacy responsebody <pattern> form is deprecated and returns unsupported_action.

The crabcode-browser executable lookup order is: the custom path from CRABCODE_BROWSER_BINARY, then beside the running executable, then <exe>/bin/, then ~/.crabcode/bin/. High-risk actions (evaluate arbitrary JS, upload, download, fill --submit, JS wait predicates) require explicit permission or CRABCODE_BROWSER_ALLOW_RISKY.

Extension mode attaches to the Chrome you are already using through CrabCode in Chrome. It reuses your real accounts, cookies, browser extensions, and site permissions — good for debugging systems that require login, OAuth/SSO, intranet pages, and anything only reachable from your daily Chrome.

The package and the illustrated steps live here: CrabCode browser extension setup.

You can also open extension settings from the TUI:

shell

/chrome
/chrome

The onboarding menu adapts to the current state:

Install Chrome extension — opens the extension setup guide
Reconnect extension — re-establishes the extension ↔ CrabCode connection
Manage permissions — jumps to the extension's site-permission management
Enabled by default: Yes/No — controls whether new sessions auto-enable extension mode

If Chrome assigns an extension id different from CrabCode's placeholder id, set CRABCODE_CHROME_EXTENSION_ID to the real id and restart CrabCode so the native host manifest allows the extension to connect.

Tools the model gets (40 public tools)

In extension mode the model uses the crabcode-in-chrome skill and a set of mcp__chrome-automation__* tools (built-in browser mode pairs with the crabcode-browser skill). The 40 public tools, grouped by purpose:

Automation (click / type / forms / navigation)

Tool	Purpose	Risk
`computer`	Click an element	Visible write
`form_input`	Type into a form field	Sensitive write
`form_fill_form`	Fill a whole form	Sensitive write
`navigate` / `navigate_back` / `navigate_forward` / `reload_page`	URL navigation / back / forward / reload	Visible write
`resize_window`	Resize the window	Visible write
`handle_dialog`	Handle alert / confirm / prompt	Visible write
`shortcuts_execute`	Simulate key presses	Visible write
`tabs_create_mcp`	Open a new tab	Visible write
`update_plan`	Submit a plan (model → user confirmation)	Read-only

Observation (read page / elements / logs)

Tool	Purpose	Risk
`read_page` / `get_page_text`	Read DOM / plain text	Read-only
`find`	Find elements	Read-only
`take_screenshot`	Lightweight screenshot	Read-only
`read_console_messages`	Read console (supports `pattern` regex filter)	Read-only
`read_network_requests`	Read network requests	Read-only
`tabs_context_mcp` / `shortcuts_list`	List tabs / list available shortcuts	Read-only
`wait_for`	Wait for an element / condition	Read-only
`session_list` / `session_inspect` / `cdp_list`	List sessions / inspect a session / list CDP targets	Read-only

Artifacts (GIF / PDF / HAR / trace / playback)

Tool	Purpose	Risk
`gif_creator`	Record a GIF (multi-step replay)	Sensitive write
`print_pdf`	Export the page as PDF	Sensitive write
`export_har`	Export HAR (network capture)	Sensitive read
`export_trace`	Export a replayable trace	Sensitive read
`export_playback`	Export a playback manifest	Sensitive read

Storage / upload

Tool	Purpose	Risk
`upload_image`	Upload a file into a form	Sensitive write

High risk (arbitrary JS)

Tool	Purpose	Risk
`javascript_tool`	Run arbitrary JavaScript in the page context	High risk

Advanced sessions (session / CDP)

Tool	Purpose	Risk
`session_create` / `session_select` / `session_pause` / `session_resume` / `session_close` / `session_reset`	Create / select / pause / resume / close / reset sessions	Visible write
`cdp_attach` / `cdp_detach`	Attach to / detach from an external CDP target	Visible write
`cdp_command`	Send a raw CDP command	Sensitive write

Which mode to pick

Task	Recommended mode
Open localhost for frontend verification, screenshots, console reads	Built-in browser mode
CI / automation scripts / isolated browser profiles	Built-in browser mode
Reuse the login state, cookies, and extensions in your Chrome	Extension mode
OAuth / SSO / corporate intranet / pages behind human verification	Extension mode
Not sure	Start with built-in browser mode, switch explicitly to extension mode when real login state is needed

Typical use

shell

open localhost:3000, sign in, then check the dashboard for console errors
open localhost:3000, sign in, then check the dashboard for console errors

This defaults to built-in browser mode: launch isolated Chromium → navigate → fill the form → wait for load → read console → report.

shell

open the company admin with my current Chrome login and inspect the order page's network requests
open the company admin with my current Chrome login and inspect the order page's network requests

This needs extension mode: confirm CrabCode in Chrome is installed and connected, then read the current Chrome tab and its network requests.

Limits and caveats

Don't treat the extension as the default: extension mode can see your real login state — disconnect when done; prefer built-in browser mode for ordinary page verification.
The two modes do not share state: being logged in under built-in browser mode does not mean extension mode is logged in, and vice versa.
Don't trigger native dialogs: alert / confirm / prompt block the extension; have the model take over with handle_dialog (extension mode) or the dialog command (built-in browser mode) first.
Console output is verbose by default: have the model filter with pattern or --filter to cut noise.
Stop after 2-3 failures: don't let the model retry the same failing action in a loop.
Be careful screenshotting or exporting sensitive pages: mail, payment, admin, and identity pages may contain tokens or private data.

Troubleshooting

Symptom	Common cause	Fix
Desktop says "built-in browser not found"	The release is missing the `crabcode-browser` executable	Update to the latest CrabCode desktop (the release bundles it); or set `CRABCODE_BROWSER_BINARY` to the `crabcode-browser` executable path
Built-in browser mode pages lack your login state	Built-in browser mode uses an isolated Chromium profile	Switch to extension mode, or sign in separately inside the built-in browser profile
Extension mode says the browser bridge is not connected	Extension not installed, native host not registered, or the current page not attached	Open the extension setup guide, verify the extension is enabled in `chrome://extensions`, then reconnect
Extension side panel shows "Not connected"	Native host manifest does not match the extension id	Set `CRABCODE_CHROME_EXTENSION_ID` to the real id shown by Chrome and restart CrabCode

Browser extension setup guide
input-modalities
skills (pair built-in browser mode with the crabcode-browser skill, extension mode with crabcode-in-chrome)
security