dashi96/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 plain
chrome.tabs / chrome.scripting / chrome.debugger, so it works in any
Chromium browser that can load an extension.
Demo
Claude driving the browser through the bridge — opening Wikipedia, typing a
search, and landing on the article:
Architecture
- extension/ — an MV3 extension: the service worker keeps a WebSocket to the
local 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 to
Claude Code and proxies them to the extension. It accepts WS connections
only from a chrome-extension://… Origin — regular web pages cannot connect.
It also serves the /chat channel: panel messages run through the
Claude Agent SDK (authenticated via the Claude Code login) with the same
browser_* 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 you
click the extension icon (no chrome.sidePanel — it is not supported
everywhere). The chat can see the browser: list tabs, read pages, take
screenshots, and click.
The panel UI is in English by default and switches to Russian automatically
when the browser UI language is Russian. A language selector (Auto / English /
Русский) in the bottom bar overrides auto-detection; the on-page badge follows
the same choice.
- The popup closes when it loses focus (clicking the page) — that is browser
behavior. The conversation context is not lost: the panel remembers the
session_id and the server resumes the conversation via the Agent SDK
resume. A turn that is in flight when the popup closes is interrupted.
- It only works while the server is running (usually an active Claude Code
session 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 not
read Claude Code settings themselves, the server passes the model
explicitly), the other entries are hard overrides. Switching applies on the
fly (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; the
extension always connects to 8929, so changing the port also means editing
WS_URL in extension/sw.js and extension/chat.js.
- Chat history: the 🕓 button in the header lists past conversations (stored
in 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 is
an 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 per
message) — the model sees them; only a marker remains in history.
- "Ask before acting" mode (checkbox above the input): reading (tabs, text,