Chromium Bridge

Chromium Bridge

Русская версия

A bridge between your Chromium-based browser and Claude Code. The official"Claude in Chrome" extension connects in some Chromium browsers (Arc, Vivaldi,and others) but automation hangs: its tools are built on the tab groups API,which is missing or broken there. This bridge uses only plainchrome.tabs / chrome.scripting / chrome.debugger, so it works in anyChromium browser that can load an extension.

Demo

Claude driving the browser through the bridge — opening Wikipedia, typing asearch, and landing on the article:

Architecture

Claude Code ⇄ (stdio MCP) ⇄ server/index.mjs ⇄ (WebSocket, 127.0.0.1:8929) ⇄ extension in the browser
                                   ⇅ (WebSocket /chat)
                            chat panel (popup on the extension icon)

• extension/ — an MV3 extension: the service worker keeps a WebSocket to thelocal server and executes its commands (tabs, navigation, page text,screenshots, clicks, form filling). Clicking the icon opens the chat panel(chat.html) — a popup anchored to the extension icon.
• server/ — an MCP server (stdio) that exposes the browser_* tools toClaude Code and proxies them to the extension. It accepts WS connectionsonly from a chrome-extension://… Origin — regular web pages cannot connect.It also serves the /chat channel: panel messages run through theClaude Agent SDK (authenticated via the Claude Code login) with the samebrowser_* tools; built-in tools (Bash, Read, etc.) are disabled.

Chat panel

An equivalent of the "Claude in Chrome" side panel: a popup that opens when youclick the extension icon (no chrome.sidePanel — it is not supportedeverywhere). The chat can see the browser: list tabs, read pages, takescreenshots, and click.

The panel UI is in English by default and switches to Russian automaticallywhen the browser UI language is Russian. A language selector (Auto / English /Русский) in the bottom bar overrides auto-detection; the on-page badge followsthe same choice.

• The popup closes when it loses focus (clicking the page) — that is browserbehavior. The conversation context is not lost: the panel remembers thesession_id and the server resumes the conversation via the Agent SDKresume. A turn that is in flight when the popup closes is interrupted.
• It only works while the server is running (usually an active Claude Codesession with the chromium-bridge MCP); otherwise the panel shows"Server unavailable".
• Model picker in the panel header: "Default" takes the model from~/.claude/settings.json (whatever was set via /model; SDK sessions do notread Claude Code settings themselves, the server passes the modelexplicitly), the other entries are hard overrides. Switching applies on thefly (setModel) and is remembered. Startup override:CHROMIUM_BRIDGE_CHAT_MODEL=sonnet in the server environment.Port: CHROMIUM_BRIDGE_PORT (8929 by default) — server side only; theextension always connects to 8929, so changing the port also means editingWS_URL in extension/sw.js and extension/chat.js.
• Chat history: the 🕓 button in the header lists past conversations (storedin the panel's localStorage, the last 30).
• After each turn there is a usage line: turn tokens (↑ input incl. cache /↓ output) and the accumulated session cost in $ (on a subscription this isan estimate, not a separate bill).
• Screenshots the agent takes along the way are shown right in the chat feed(click to expand). They are not saved to history (localStorage is finite).
• You can paste images from the clipboard (Cmd+V in the input, up to 5 permessage) — the model sees them; only a marker remains in history.
• "Ask before acting" mode (checkbox above the input): reading (tabs, text,screenshots, console, network) proceeds without questions, while mutatingactions — clicks/typing/navigation/JS/forms/closing tabs/file uploads —wait for an Allow / Deny card. The agent sees a denial and continues theconversation. Toggling applies immediately, without recreating the session(via the Agent SDK's canUseTool).

On-page indication

When Claude acts on a tab (from the panel or from Claude Code):

• an orange glow burns around the page edges with a "✳ Claude is working…"badge, fading 2.5s after the last action;
• a virtual cursor (an orange arrow) glides to the action point and pulses aring on click; it disappears after 3.5s of inactivity.

Both are hidden on screenshots so they don't end up in the frame and confusethe model when working with coordinates. On pages where scripts cannot beinjected (chrome:// and the like) the indication is silently skipped.

Installation

1. Extension: clone this repository, open chrome://extensions (in theright space/profile!), enable "Developer mode", click "Load unpacked", andpick the extension/ folder.

2. MCP server — either way:

   • via npm: claude mcp add -s user chromium-bridge -- npx chromium-bridge
   • from the clone: cd server && npm install, thenclaude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs".

   It loads at session start — restart your Claude Code session afterinstalling the extension.

   For other MCP clients, add this to your config:

   {
     "mcpServers": {
       "chromium-bridge": {
         "command": "npx",
         "args": ["chromium-bridge"]
       }
     }
   }
   

3. Check: the browser_status tool should return {"connected": true}.

Tools (v0.5)

Everything except basic tab operations works through chrome.debugger (CDP):screenshots don't require activating the tab, clicks are real mouse events,and console/network are collected from the first CDP touch of the tab.

Limitations

• The extension lives in one browser profile — install it in the one you wantto automate.
• While the server is running, its periodic ping keeps the extension's serviceworker awake. If the worker is asleep anyway (e.g. the server has juststarted), a keepalive alarm wakes it within ~30 seconds, and the server waitsup to 12 seconds for reconnection before erroring.
• Trust model: the WS server listens on 127.0.0.1 and rejects connectionswhose Origin is not chrome-extension://…, which keeps web pages out. Itdoes not distinguish between extensions, and a non-browser local process canfake the Origin header — anything running as your user is trusted, like withmost local dev tools. Don't run the bridge on a shared machine.
• On the first CDP action the browser shows a "Chromium Bridge starteddebugging this browser" bar — that's normal, the debugger is the controlmechanism. Closing the bar detaches the debugger (the next actionre-attaches it).
• Console/network are not recorded retroactively — only after the tab isfirst touched.
• Port 8929 is owned by one session: a second parallel Claude Code sessioncannot start its own WS server (the extension stays with the first one).

License

MIT