Docs · beta 0.3

Getting started

About ten minutes. You need Chrome, Node.js 20 or newer, and an MCP client such as Claude Code or the Codex CLI. Early-access builds come with these steps; ask for one.

1. Install and build

npm ci
npm run build                     # produces the extension/ folder
npm run bridge -- --print-token   # your pairing token (shown once, never logged)

2. Load the extension

Open chrome://extensions and turn on Developer mode.
Click Load unpacked and choose the extension folder.
Click the BrowserZap toolbar icon to open the side panel.
Under Settings → Pairing token, paste the token from step 1.

3. Connect your agent

npm run config prints the exact snippet for your paths and clients; it never edits your configuration itself. For Claude Code:

claude mcp add browserzap --scope user -- node "<folder>\bridge-server\index.js"

The MCP server starts the bridge when needed and authenticates on its own, so your client configuration never contains the token.

4. Check it

npm run health          # every line should say PASS
npm run check:chrome    # a guided check in your own Chrome

Several Chrome profiles

Using a work and a personal profile? Load the extension in each profile, paste the same token, and name each one under Settings → Profile name. When more than one profile is connected, your agent chooses with browser_select_profile; until it does, BrowserZap refuses with PROFILE_REQUIRED rather than guess. To pin an agent to one profile, set BROWSERZAP_PROFILE in its MCP configuration.

Workflows

Teach by demonstration: in the side panel, press Record, do the task once yourself, review the steps and save.
From your agent: workflow_record with action: "start", do the task, then action: "stop".
Replay from the side panel with new values (no agent needed), or with workflow_run.
Batches (Pro): workflow_run with paramSets runs once per person or row; one failure does not stop the rest. Read the reports with npm run runs.

When something is slow or fails

Every slow or failed step carries likelyCause:

likelyCause	Meaning	What to do
`server_slow`	The site's server has not answered (the request is named)	Allow more time (`timeoutMs`, up to 120000)
`downloading`	The page is still loading	Allow more time
`still_rendering`	The page shows a spinner or "Loading…"	Allow more time
`page_busy`	The page did not respond (heavy script)	Retry; check the tab
`server_error`	The site answered with an HTTP error	Retry later if `retryable`
`not_on_page`	Nothing is loading and the element is not there	Inspect the page; the site may have changed

Your session log is one command away: npm run logs. It never contains what you typed.