Browser Bridge (BBX)

Chrome Web Store: Install Browser Bridge (BBX) from the Chrome Web Store. For local or custom builds, use the unpacked install flow in docs/unpacked-extension.md.

A local bridge between your coding agent and a real Chrome tab. Browser Bridge gives the agent structured access to DOM, styles, layout, console, network, accessibility data, reliable browser input, explicit JavaScript dialog handling, and reversible patches - starting from the actual tab you already have open, with all its real state intact.

See Quickstart to get started in another repo, or browse the rest of the guides in docs/index.md.

Supported Agents

Managed installs support Codex (OpenAI), Claude Code, OpenCode, GitHub Copilot, Cursor, Devin Desktop (formerly Windsurf), Antigravity, Gemini CLI, Cline, Zed, Amp, Factory Droid, Pi, Kilo Code, Qwen Code, Goose, OpenHands, Muse Code, Grok Build, and generic .agents layouts for MCP and CLI skills. Devin Desktop keeps the windsurf setup target for compatibility. Cline, Goose, OpenHands, and Muse MCP setup is user-scope only; their CLI skills also support projects. Zed support targets its native agent; external agents keep their own configuration.

OpenAI Codex	Claude Code	Cursor	GitHub Copilot
			.agents
OpenCode	Antigravity	Windsurf	Generic agents

What it's for

• Debugging a UI on localhost: read DOM, computed styles, layout, console logs, and network state without a screenshot
• Exporting sanitized, metadata-only HAR 1.2 evidence after explicitly capturing a network reproduction
• Verifying a code change actually rendered the expected result in Chrome
• Patching the live page to prove a fix visually, then moving it into source and rolling the patch back
• Running structured browser checks from any local agent or IDE, not just one AI product
• Calling website-provided WebMCP tools when the browser supports them, with exact-action user approval and DOM verification

Why Browser Bridge

Most adjacent tools optimize for different goals. Playwright and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. Claude in Chrome is great for integrated Claude workflows, and the Codex extension is a great option if you use Codex, but both are vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.

Browser Bridge is optimized for the opposite starting point: inspect the state that already exists in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to one explicitly enabled browser window rather than ambient browser control.

Setup

1. Install Browser Bridge from the Chrome Web Store in Chrome or another Chromium-based browser
2. With Node.js 20 or later installed, run npm install -g @browserbridge/bbx. The npm launcher downloads the matching Go executable, verifies its pinned SHA-256 digest, and registers the native messaging host.
3. Return to the extension and choose your agent under Connect your agent. Start with MCP.
4. Enable access for the browser window you want the agent to use.
5. Ask your agent to use Browser Bridge.

The npm package is a bootstrap and launcher with zero runtime npm dependencies. It downloads the exact package version for macOS arm64/x64, Linux arm64/x64, or Windows x64 from GitHub Releases. The Go executable runs the CLI, daemon, native host, and MCP server. Local dependency installs do not register a browser; if install scripts were skipped, the first command downloads the executable, then run bbx install to register it. See the native CLI guide.

If the extension does not connect, run bbx install. Register a specific browser with bbx install --browser chrome|edge|brave|chromium|arc.

On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.

MCP mode is self-contained: the dual-era stdio server supports legacy MCP clients and modern stateless MCP revision 2026-07-28, and exposes tools and matching startup instructions without requiring a separate CLI skill.

How it works

• The extension is scoped to one explicitly enabled Chrome window at a time - no ambient browser access
• Requests default to the active tab in that window unless a tab is targeted explicitly
• Targeted input actions reject hidden, disabled, ambiguous, stale, or obscured targets instead of silently guessing; their responses report the resolution and DOM/CDP execution path (cdp_press_key and scroll_into_view use separate contracts)
• Native pointer/text input, dialog handling, all-resource network capture, accessibility trees, screenshots, and raw CDP reads use the existing debugger permission only when requested
• HAR export is a read of an already armed CDP capture: start capture, reproduce, export, then stop. Export never starts, stops, or clears capture, and omits headers, cookies, bodies, authorization values, and unsupported size/timing detail
• HAR and screenshot artifacts are opaque, owner-scoped daemon handles with a five-minute lifetime and no browser-host path; CLI capture commands download, verify, delete, and write them on the CLI host
• File workflows include staged uploads, trusted PNG paste, and browser-native large downloads with progress, pause/resume, and cancellation
• Opt-in recording supports child-tab watch, timing correlations, durable crash-recovery journals, continuous renderer playback, and local MP4 export
• Element references are document-local and strict by default; stale input recovery is opt-in, same-document, requires one strong unique semantic match, and fails safely when its bounded scan cannot prove uniqueness
• Semantic DOM baselines provide explicit create/compare/describe/release verification without modifying the page; compact snapshots stay memory-only, expire after five minutes, and are invalidated by navigation or access teardown
• Patches keep per-document rollback history and Browser Bridge attempts best-effort rollback when window access is disabled or switched; committing the patch baseline keeps current changes but discards their rollback history
• URL waits observe full navigation and same-document SPA changes, and report the final URL and observed navigation kind
• Structured DOM/style/layout reads are the primary transport; screenshots are a fallback
• Browser input dispatch does not prove the application accepted the intended change, so agents should verify with a wait or structured read
• Open-ended investigation should start with structured reads on a smaller, lower-cost subagent when the client supports delegation
• Recovery diagnostics use process-local five-minute counters for six fixed, content-free categories. health.ping, daemon.metrics, and bbx doctor expose no page data; three failures in the same category group within 60 seconds produce an active-loop warning and fixed recovery guidance
• Performance reads are raw browser-maintained CDP counter point samples with browser-defined names and units, not Web Vitals or Browser Bridge navigation measurements
• The native host daemon auto-starts on demand

Documentation

• Quickstart
• Usage scenarios
• Manual setup
• Agent permissions
• CLI guide
• MCP vs CLI
• Troubleshooting
• BridgeClient API
• WebMCP website tools
• Development and Make tasks

Privacy

The extension and native host communicate on the browser machine, and local clients connect to that daemon by default. If you explicitly configure an authenticated remote destination, bridge results can travel over your user-provided SSH tunnel or network route to the selected client. Browser Bridge does not operate a Browser Bridge cloud service, and raw remote TCP is not presented as encrypted.

Your connected agent or IDE may still forward tool calls or tool results to remote services under that product's own settings and privacy policy. See PRIVACY.md for the Browser Bridge policy.

Responsible Use

Browser Bridge is intended for local development, debugging, and testing of web resources you own, control, or are explicitly authorized to test. Do not use it for web scraping, unauthorized data collection, or impersonating or acting as another user. You are responsible for the agents you connect, the actions they perform, and compliance with applicable laws, permissions, website terms, and third-party rights. See the Responsible Use Agreement.

License

MIT. See LICENSE.