Browser Automation

CrabCode supports the default playwright-cli backend 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
CLI mode (default)	Standalone local Chromium	`playwright-cli` subprocess	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 playwright-cli. The model and the desktop Browser Automation page default to CLI mode. Use extension mode only when the user explicitly asks for their real Chrome, the task requires login state/OAuth/SSO, or the CLI 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

CLI mode: the default browser backend

CLI mode uses crabcode browser ... to call playwright-cli and launch 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
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full-page --profile dev
crabcode browser stop --profile dev
crabcode browser status --json
crabcode browser start --profile dev
crabcode browser navigate http://localhost:3000 --profile dev
crabcode browser snapshot --json --profile dev
crabcode browser screenshot --full-page --profile dev
crabcode browser stop --profile dev

Common capabilities include:

profiles, tabs, navigation, and reloads
DOM snapshots, screenshots, PDF export, console, and errors
network request lists and 1-based indexed request / response-body reads
click, type, select, upload, download, wait, and JavaScript evaluation
cookies, storage, traces, and locator highlighting

playwright-cli lookup order is: custom executable from CRABCODE_PLAYWRIGHT_CLI, project node_modules/.bin/playwright-cli, then playwright-cli on PATH. Risky actions such as arbitrary JavaScript, uploads, downloads, and submitted form fills require explicit permission or CRABCODE_BROWSER_ALLOW_RISKY.

Extension mode: your real Chrome session

Extension mode connects through CrabCode in Chrome inside your existing Chrome. It can reuse real accounts, cookies, browser extensions, and site permissions, so it is the right backend for logged-in business systems, OAuth/SSO, intranet pages, and flows that only work in your daily Chrome.

Use the CrabCode browser extension install guide for the ZIP package and setup steps.

You can also open extension settings from the TUI:

shell

/chrome
/chrome

The menu adapts to the current state:

Install Chrome extension — opens the extension install guide
Reconnect extension — re-establishes the extension ↔ CrabCode link
Manage permissions — opens per-site extension permissions
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 Chrome's real id and restart CrabCode so the native host manifest allows the extension to connect.

In extension mode, the model uses the crabcode-in-chrome skill and mcp__chrome-automation__* tools. Capabilities include page reads, console/network reads, click and form actions, navigation, screenshots, GIFs, PDFs, HAR, traces, external CDP, and session management.

Which mode to pick

Task	Recommended mode
Open localhost for frontend validation, screenshot, and console reads	CLI mode
CI, automation scripts, or an isolated browser profile	CLI mode
Reuse your Chrome login state, cookies, or extensions	Extension mode
OAuth, SSO, intranet, or pages behind a completed human check	Extension mode
Unsure	Start with CLI mode, then explicitly switch to extension mode only when real Chrome state is needed

Typical use

shell

Open localhost:3000, log in, then check the dashboard for console errors.
Open localhost:3000, log in, then check the dashboard for console errors.

By default, CrabCode uses CLI mode: open isolated Chromium → navigate → fill the form → wait for load → read console → report.

shell

Use my current Chrome login to open our internal admin page and inspect the order network requests.
Use my current Chrome login to open our internal admin page and inspect the order network requests.

This requires extension mode: first make sure CrabCode in Chrome is installed and connected, then inspect the current Chrome tabs and network traffic.

Limits and caveats

Do not treat the extension as the default: extension mode can see your real logged-in browser state. Use it on demand and disconnect when done.
Backends do not share state: logging in inside CLI mode does not log you in inside extension mode, and vice versa.
Avoid native dialogs: alert, confirm, and prompt can block the extension. Use dialog handling first when needed.
Console output is verbose: ask the model to filter by pattern or keyword.
Stop after 2-3 failures: do not let the model loop on the same broken browser action.
Be careful with sensitive pages: email, payments, admin, and identity pages can expose tokens or private data in screenshots and exports.

Troubleshooting

Symptom	Common cause	Fix
Desktop says "playwright-cli not found"	CLI mode cannot find the executable	Install or repair `@playwright/cli`, or set `CRABCODE_PLAYWRIGHT_CLI=/abs/path/to/playwright-cli`
CLI mode does not have your logged-in account	CLI mode uses an isolated Chromium profile	Use extension mode, or sign in separately inside the CLI profile
Extension mode says the browser bridge is not connected	Extension not installed, native host not registered, or page not connected	Open the extension install guide, verify it is enabled in `chrome://extensions`, and reconnect
Extension side panel shows "Not connected"	Native host manifest does not match the extension id	Set `CRABCODE_CHROME_EXTENSION_ID` to Chrome's real extension id and restart CrabCode