# Chrome Bridge

> By [frsorrentino](https://github.com/frsorrentino) · npm `chrome-bridge-mcp` · not affiliated with other projects named "chrome-bridge".

![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-388%20unit%20%2B%2041%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)

**Claude Code borrows a tab from the Chrome you are already using — signed in,
with your extensions and your cookies — works in it, and hands it back. What
only a person can do (a login, a 2FA code, a CAPTCHA, a choice) comes back to
you through `handoff`: a banner in the page, you act, the agent continues.**

Measured against the official browser extension (paired runs, 29/09/2026, n=5
per task, same model): filling a form, 4.7× fewer turns and 2.8× lower cost;
finding one row in a 1,500-row table, 2.3× fewer turns and 3.4× lower cost;
debugging a broken page, 9.3× fewer turns and 4.3× lower cost. 15 correct
answers out of 15, against 12 ([bench/RESULTS.md](bench/RESULTS.md)). ~3× the toolset and no paid plan. 60
web-development tools (navigation, DOM inspection, visual regression, audits,
network mocking) over a local WebSocket bridge, plus a headless instance for
CI. Self-hosted, local-only. Works on ChromeOS.

![The same form filled in 3 turns instead of 14 — 4.7× fewer turns on the form, 2.8-4.3× lower cost on form, 1,500-row table and debugging (paired runs, 29/09/2026, n=5)](assets/readme/card1-race.png)

## Quickstart

**Requires** Node.js 18+ and Chrome 135+.

```bash
git clone https://github.com/frsorrentino/chrome-bridge.git
cd chrome-bridge && ./install.sh
```

1. Open `chrome://extensions`, enable **Developer mode**, click **Load
   unpacked**, select the `extension/` folder.
2. Restart Claude Code.

Then ask for something like *"open localhost:3000, run an accessibility audit
and find the Sign Up button"*: Claude Code calls `navigate`,
`audit` and `find_text`. Because `navigate` already returns
element refs, `click(ref="n1")` follows with no discovery turn in between.

> **On ChromeOS/Crostini** install from the [Chrome Web
> Store](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
> instead: an unpacked extension is dropped on every reboot, because the
> container isn't mounted when Chrome starts.

> **On Windows** `install.sh` does not run from PowerShell or cmd. Use the
> plugin path below (`claude plugin marketplace add frsorrentino/chrome-bridge`,
> then `claude plugin install chrome-bridge@chrome-bridge`) with the extension
> from the Web Store, or run `install.sh` from Git Bash. The plugin's error
> log hooks run in Git Bash, as Claude Code runs every hook, and need Python
> 3.8+ as `python3`, `python` or `py` (the Microsoft Store `python3` alias is
> skipped); without Python they stay silent and the tools work the same. For
> launch mode see `CHROME_BRIDGE_BROWSER` below: Google Chrome cannot load the
> extension there, Microsoft Edge can.

`install.sh` registers the MCP server with `--scope user`. To do it by hand:
`claude mcp add --scope user chrome-bridge node /path/to/server/index.js`.
For `execute_js`, enable **Allow user scripts** in `chrome://extensions` →
Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).

**As a plugin, without a clone:** inside a Claude Code session,
`/plugin install chrome-bridge --marketplace frsorrentino/chrome-bridge`
(one command, Claude Code 2.1.275+; on older versions `/plugin marketplace add
frsorrentino/chrome-bridge` then `/plugin install chrome-bridge@chrome-bridge`).
From a shell, `claude plugin install` has no `--marketplace` option: run
`claude plugin marketplace add frsorrentino/chrome-bridge`, then
`claude plugin install chrome-bridge@chrome-bridge`. Either way the plugin
registers the MCP server from npm (all capabilities) together with the recipes
skill; clients that read [Agent Plugins 1.0](https://agent-plugins.org) get the
same from `plugin.json` + `mcp.json`. The extension still comes from the Web
Store or `extension/`. Pick one path: the plugin and `install.sh` would
register the same server twice, and so would a plugin added from the
[Anthropic directory](https://claude.ai/directory) on claude.ai (it reaches
Claude Code as `chrome-bridge@synced`) next to a marketplace install. In
claude.ai chat the plugin loads only the recipes skill: the tools need Claude
Code, or Cowork running on your computer, where the local MCP server can start.

## Your browser, your login

No blank profile, no debugging port, no cloud browser. The extension runs in
your Chrome, so every site you are signed into is already open to the agent:
webmail, the hosting panel, a client's back office, a staging site behind
basic auth. Tabs the agent opens are marked as its own and closed when the
session ends; your tabs stay yours.

When a page asks for something only you can give, the agent does not guess and
never types credentials. `handoff` shows a banner in the page with what it
needs — "complete the login with your 2FA, then press Done", "click the button
you mean" — waits for you, and continues from where you left it, redirects
included. It can also ask a question in the banner and read your typed reply,
or let you pick one or more elements on the page.

## Why Chrome Bridge?

| | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
|---|---|---|---|---|
| **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
| **Tools** | **60** (43 core) | 22 | 29 default (56 with flags) | 24 core (71 total) |
| **Requires paid plan** | **No** | Yes (Pro+) | No | No |
| **Network mocking** | **Yes** (stub/headers) | No | No | Yes |
| **Visual regression** | **Yes** (`screenshot_diff`) | No | No | No |
| **Audits (a11y/SEO/sec)** | **Yes** (one call, report on disk) | No | Lighthouse | No |
| **Headless / CI** | **Yes** | No | Yes | Yes |
| **GIF / video** | No | **Yes** | Partial | No |
| **Breakpoints / heap** | No | No | **Yes** | No |

Codex for Chrome (OpenAI, May 2026) sits in the Claude in Chrome column: an
official extension with the `debugger` permission, macOS and Windows only,
the ChatGPT app required. Claude in Chrome documents Linux desktop since
September 2026; ChromeOS and WSL stay out. Competitor figures measured on
2026-09-01 and 2026-09-11 (`docs/analisi-2026-09-11-concorrenti.md`).

It wins on **round trips** — short element refs instead of the
screenshot-and-click loop, `fill_form` filling N fields in one call — and, on
big pages, on **payload**: table filtering is done server-side. On the form, per single turn it actually costs
slightly *more*.

The full benchmark — method, every raw run including the unfavourable ones, and
what the harness can't measure — is in
[docs/EFFICIENCY.md](docs/EFFICIENCY.md).

![Claude checks its own work: console errors, pixel diffs, network mocking and audits](assets/readme/card5-devloop.png)

## Using it

The **skill** in [`skills/chrome-bridge/SKILL.md`](skills/chrome-bridge/SKILL.md)
is what makes the tools discoverable: recipes with the phrase that triggers
each one ("verify the email arrives", "test the checkout with a test card",
"which plugin slows the page", "what fires before consent"), the tool sequence,
and the zero-token CLI commands the model would otherwise never see.
`install.sh` copies it to `~/.claude/skills/chrome-bridge`; do the same by
hand for other clients.

Beyond the MCP tools, two lanes keep work away from the model entirely.

![Some jobs never touch the model: the CLI lane runs the same tools at zero tokens](assets/readme/card3-lane.png)

**CLI** — batch operations, piped through `grep` or `jq` before anything reaches
the context:

```bash
chrome-bridge navigate --url https://example.com
chrome-bridge read_console --level error | head -20
chrome-bridge assert --selector "#success" --text "Done"
chrome-bridge replay --file ./recordings/login.jsonl
```

**Launch mode** — a dedicated Chromium instance with an ephemeral profile, for
isolated sessions or CI:

```bash
node server/index.js --launch --headless
```

It looks for Chromium, Microsoft Edge, Brave and last Google Chrome in their
standard paths on Linux, macOS and Windows; `CHROME_BRIDGE_BROWSER` picks
another binary. Google Chrome 137+ ignores `--load-extension`, so the
extension never connects in it: use Chromium, Edge, Brave or Chrome for
Testing.

Pair it with `session_record` + `replay` for smoke tests with no model in the
loop. In launch mode `execute_js` falls back to `new Function` when the
user-script toggle isn't available.

## Tools

66 in total. `core` (43 tools, every tool used in 101 real sessions) loads by
default; the other 23 sit in seven optional caps that the agent switches on
mid-session with `get_status({enable: ["visual"]})`, with no restart
(`--caps` still sets them at startup).

![66 tools in eight groups, from clicking a button to tracing a page](assets/readme/card4-toolbox.png)

| Group | N | What's in it |
|---|---|---|
| Core & Navigation | 13 | tabs, windows, `navigate`, `screenshot`, `tile_windows` |
| Interaction | 11 | `click`, `fill_form`, `upload_file`, dialogs, clipboard |
| DOM & Inspection | 12 | `read_page`, `extract`, `extract_table`, `query_dom`, `get_css_styles`, `watch_dom` |
| Debugging & Network | 8 | `execute_js`, console, network log, mocking, `track_events` |
| Visual & Responsive | 5 | `screenshot_diff`, viewport and zoom, media emulation |
| Audits | 2 | `audit` (a11y, keyboard, SEO, security, links, vitals, css, resources, cache in one call), `cookie_audit` |
| State, Storage & Files | 9 | storage, fixtures, MHTML, recording, `assert` |
| Motion & Performance | 6 | `animations`, `frames` (long frames, CLS, INP), `perf_trace`, `screencast`, `lighthouse` and `heap_snapshot` (launch mode) |

Every tool, with the notes that matter: [docs/TOOLS.md](docs/TOOLS.md).

## How it works

![It drives the Chrome you are logged into, over a local WebSocket bridge](assets/readme/card2-bridge.png)

```
Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
                          (server/)                          (extension/, MV3)
```

The Node.js server handles the protocol and tool logic; the MV3 extension
executes commands through Chrome APIs. User scripts (`execute_js`) run via
`chrome.userScripts.execute()`.

## Configuration and security

Environment variables, each with a matching CLI flag:

| Variable | Default | Notes |
|---|---|---|
| `CHROME_BRIDGE_PORT` | `8765` | |
| `CHROME_BRIDGE_HOST` / `--host` | `127.0.0.1` | `0.0.0.0` **only** where the browser lives outside the container (ChromeOS/Crostini port-forward) — and only with a token |
| `CHROME_BRIDGE_TOKEN` | unset | Required on both `ext_init` and `relay_init`. Strongly recommended whenever the bind isn't loopback |
| `CHROME_BRIDGE_CAPS` / `--caps` | `core` | `core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, `all`. Optional caps can also be switched on at runtime with `get_status({enable})` |
| `CHROME_BRIDGE_ALWAYS_LOAD` / `--always-load` | 22 most used tools | Tools kept in context when the client loads the server whole; the others carry `_meta['anthropic/alwaysLoad'] = false` and wait behind tool search (Claude Code 2.1.285+). `all` loads every tool; a comma list picks them |
| `CHROME_BRIDGE_NO_JS` / `--no-js` | unset | No arbitrary JavaScript in the page: `execute_js` and `modify_dom` leave the schema, `wait_for(condition=function)` and `javascript:`/`data:` URLs are refused. `get_status` reports `js_evaluation` |
| `CHROME_BRIDGE_READ_ROOT` / `--read-root` | unset | Where `upload_file` may read from. Unset: any file except keys and credentials (`~/.ssh`, `~/.aws`, `~/.gnupg`, `.env*`, `id_*`, `*.pem`, `*.key`, …), symlinks resolved first. Set: only files under this directory, whatever their name — the way to upload a certificate key on purpose |
| `CHROME_BRIDGE_BROWSER` | unset | Launch mode only: the browser binary, e.g. `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`. Unset: the first of Chromium, Edge, Brave, Google Chrome found in the standard paths (on Linux Chromium, then Google Chrome). Google Chrome 137+ cannot load the extension |
| `CHROME_BRIDGE_OBSERVE` | unset | `off` stops the local error log below. The plugin sets `hook`: its hooks keep the log and the server stays out of it |
| `CHROME_BRIDGE_WRITE_ROOT` / `--write-root` | unset | Every path the model chooses (`save_to`, `output_path`, exports) must be under this directory, checked before the browser does any work; the server's own state under `~/.config/chrome-bridge` stays writable. The CLI is your shell and is not restricted |

The bridge binds loopback, accepts extension connections only from a
`chrome-extension://` origin, and — when a token is set — requires it on both
handshakes. Without one, any local process could act as a relay and reach
`execute_js` inside your authenticated browser session. Secondary MCP instances
connect via loopback and are acknowledged with `relay_init_ok`, so a foreign
process holding the port fails fast instead of timing out per command.

**What is *not* protected:** page content reaches the model unfiltered, so a
hostile page's text is untrusted input. `get_storage`, `session_fixture`, HAR
exports and screenshots are **not** redacted and may carry cookies, tokens or
personal data. Don't point the automation at pages holding secrets you wouldn't
paste into a chat.

### Threat model

chrome-bridge gives an AI agent your real, logged-in browser. Scanners that
rate MCP servers by capability flag it, correctly, for code execution
(`execute_js`), requests that carry your cookies (`http_request`) and reading
private page data (`get_storage`, `get_tabs`). Those are the product, not bugs.
What matters is who can reach them and what a hostile page can make the agent
do with them.

- **Who can connect:** see above — loopback bind, `chrome-extension://` origin
  check, `CHROME_BRIDGE_TOKEN` on both handshakes.
- **Launch mode also opens a DevTools port** on 127.0.0.1 (chosen by the
  system), for `lighthouse` and `heap_snapshot`. CDP has no authentication:
  any local process can drive that dedicated browser while it runs. Its profile
  is temporary and holds nothing of yours; your own Chrome never gets a port.
- **The debugger bar is the signal.** `click`/`press_key` with `trusted`,
  `emulate_media via: "debugger"`, `perf_trace` and `screencast` attach
  `chrome.debugger` to one tab only for that work; Chrome shows its "started
  debugging this browser" bar meanwhile, and cancelling it ends the work.
- **The real risk is prompt injection.** A page can ask the agent to run
  JavaScript, send a request with your cookies, submit a form or upload a file.
  Treat every page you automate as untrusted input, and review what the agent
  proposes on sites that hold money or credentials.
- **Reduce the surface:** `--caps core` (the default) exposes the smallest set;
  `--no-js` removes arbitrary JavaScript; `--write-root` fences every path the
  model writes; `upload_file` refuses keys and credentials, and `--read-root`
  fences it to one directory. For sessions that matter, automate in a separate
  Chrome profile.
- **`--no-js` is not a sandbox:** `inject_css` stays, and CSS attribute
  selectors with `url()` can leak attribute values to a remote host.
- **What leaves your machine** is what the browser sends on the agent's behalf.
  chrome-bridge itself has no telemetry; the error log below stays local unless
  you approve an issue.

### Local error log

When one of its own tools fails, chrome-bridge adds a line to a **local** file,
`${XDG_STATE_HOME:-~/.local/state}/claude-observe/chrome-bridge.jsonl` (mode
0600, in a 0700 folder), in the [claude-observe](https://github.com/frsorrentino/claude-observe)
format (the plugin's copy is in `observe/`). With the plugin, a `PostToolUseFailure` hook writes it; with the npm
server alone, the server does. The same error seen again is one line with a
count.

- **Kept:** the tool name, the error text after scrubbing (your home folder
  becomes `~`; emails, URL queries, secrets and typed values are removed), the
  names of the parameters and the length of text values, the chrome-bridge
  version, the OS, the name of the working folder and of the Claude Code config
  folder. With the plugin, also the Claude Code and model versions, the
  session id and the names of the last three tools called.
- **Never kept:** parameter values — no URLs, selectors, typed text or page
  content.
- **Nothing leaves your computer** unless you say yes. With the plugin, once
  a few errors have piled up (or one has waited a few days, or one is marked
  as a defect), a line at the end of a turn tells you so, and Claude may offer,
  at a natural moment, to send them as one GitHub issue: it shows you the
  anonymized text first, then asks with buttons (from your GitHub, or not now)
  and sends only what you chose. `/chrome-bridge:observe send` does the same
  on demand; `list`, `mark` and `add` read and triage the log. The server
  alone never sends or offers anything.
- **Security observations** (a read or write outside the perimeter, a secret
  exposed, unwanted code execution, data leaving the computer) never enter a
  public issue: `/chrome-bridge:observe send --security` prepares a private
  vulnerability report for the maintainers, see [SECURITY.md](SECURITY.md).
- **Turn it off:** `{"enabled": false}` in `~/.config/claude-observe/config.json`
  (every plugin that uses claude-observe), or `CHROME_BRIDGE_OBSERVE=off` for
  the server. Keep the log but stop the offers: `{"propose": false}`.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `Chrome extension not connected` | Extension disabled, or its port differs from the server's. The error names the actual host/port; check them in the popup (⚙). |
| Port 8765 already in use | Expected: a second MCP session becomes a **relay** and shares the one bridge. Set `CHROME_BRIDGE_PORT` for a separate one. |
| `Port N is held by a process that is not chrome-bridge` | Something else owns the port. Free it or change `CHROME_BRIDGE_PORT`. |
| `execute_js` fails | Enable **Allow user scripts** in `chrome://extensions` → Chrome Bridge → Details (Chrome 138+; on 135-137 enable Developer Mode). |
| `read_console` returns `note=Instrumentation not loaded` | The page was opened before the extension, "Capture console & metrics" is off, or the page isn't injectable (`chrome://`). Reload it. |
| Screenshot times out, or `image readback failed` | A minimized or fully covered window stops producing frames; captures fail after 10 s. Bring the window forward. |
| `wait_for`/`scroll` return `page_hidden: true`, pages stop updating | Same cause: Chrome does not render a hidden page and slows its timers (after a few minutes, to one wake-up per minute). `get_page_info` reports `visibility`. Bring the window on screen, or `create_tab` with `new_window` and bounds. |
| `screenshot presets` says `NOT APPLIED` | Presets resize the window; they do not emulate a phone (no device pixel ratio, UA or touch). The window manager enforces a minimum width, and no window exceeds the screen (e.g. at most a 1536×686 viewport on a 1536×864 ChromeOS screen). For phone emulation use `emulate_media` with `device` (via debugger), or a headless browser for larger viewports. |
| `type_text` returns `mismatch: true` | The field rejected the value. Events from an extension have `isTrusted: false`, and some widgets (date pickers, search boxes with tokenizers) discard them. Try `mode: 'keys'`, then the site's own controls (the calendar buttons), or `handoff`. |
| `[media removed: request limit]` instead of a screenshot | Written by the MCP client, not by the bridge: too many images in one request. Use `save_to`, or `element_screenshot` with `region` and a small `scale`. |
| Commands work, then stop | The MV3 service worker restarted and in-memory state (network log, diff baselines, HTTP auth) was reset. Re-run the monitoring call. |
| Extension dropped on every ChromeOS reboot | Install from the Web Store instead of Load unpacked. |
| Tool missing from the list | It's in an opt-in group. Check `get_status` → `caps_available`, then set `CHROME_BRIDGE_CAPS=all`. |
| `claude mcp get` shows no command, arguments or environment | Expected with the plugin: since Claude Code 2.1.285 it hides them for stdio servers that plugins provide (variable names stay). `get_status` reports the server and extension versions, mode, host, port and caps; `/mcp` shows the connection. |
| Popup says «In attesa: un altro browser è collegato», `get_status` lists `refused_browsers` | Two browsers with the extension reach the same port. The one already connected keeps the bridge; the other retries every 15 s and takes over when the first disconnects. `get_status` → `browser` names the connected one. Before this, the last one to connect took over silently. |

## Documentation

- [docs/TOOLS.md](docs/TOOLS.md) — all 66 tools, by group
- [docs/CAPABILITIES.md](docs/CAPABILITIES.md) — what the bridge gets past and what it does not, one dated state per wall
- [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
- [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — latency per tool on the real path, `npm run bench:latency`
- [bench/RESULTS.md](bench/RESULTS.md) — raw runs and inclusion rule
- [CHANGELOG.md](CHANGELOG.md)

## Tests

`npm test` (Chrome-free, ~22s) · `npm run test:e2e` (needs Chrome and a
connected extension; with a bridge already on 8765:
`CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch`, which opens
its own Chromium with `extension/`) · `npm run measure` (schema cost) ·
`npm run bench:latency` (milliseconds per tool, launches its own Chromium,
writes `docs/PERFORMANCE.md`).

## Related projects

- [agent-webbridge](https://github.com/jeet-dhandha/agent-webbridge) — drives several Chrome profiles at once, with parallel tabs
- [awb-recipes](https://github.com/jeet-dhandha/awb-recipes) — community-maintained, dated per-site recipes for automating logged-in websites

## License

MIT