https://github.com/koltyakov/browser-bridge

🤖 Browser Bridge for Agentic AI Development - browser extension, MCP, and skilled CLI
https://github.com/koltyakov/browser-bridge

agent-tools ai-agent browser-automation chrome-extension developer-tools local-first mcp

Last synced: 22 days ago
JSON representation

🤖 Browser Bridge for Agentic AI Development - browser extension, MCP, and skilled CLI

• Host: GitHub
• URL: https://github.com/koltyakov/browser-bridge
• Owner: koltyakov
• License: mit
• Created: 2026-03-19T22:04:03.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-05-26T22:34:29.000Z (about 1 month ago)
• Last Synced: 2026-06-03T22:04:30.738Z (30 days ago)
• Topics: agent-tools, ai-agent, browser-automation, chrome-extension, developer-tools, local-first, mcp
• Language: TypeScript
• Homepage:
• Size: 1.83 MB
• Stars: 12
• Watchers: 0
• Forks: 4
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# Browser Bridge (BBX)

![Browser Bridge (BBX): Connect AI Agent and Browsers](https://raw.githubusercontent.com/koltyakov/browser-bridge/main/assets/banner.jpg)

> **Chrome Web Store:** Install `Browser Bridge (BBX)` from the [Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie). For local or custom builds, use the unpacked install flow in [docs/unpacked-extension.md](https://github.com/koltyakov/browser-bridge/blob/main/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, and reversible patches - starting from the actual tab you already have open, with all its real state intact.

See [Quickstart](https://github.com/koltyakov/browser-bridge/blob/main/docs/quickstart.md) to get started in another repo, or browse the rest of the guides in [docs/index.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/index.md).

## Supported Agents

Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, OpenCode, Antigravity, Windsurf, and generic `.agents` layouts for both MCP and CLI skill setup.

  

    

      

        

          

          

        

      

    

    

      

        

          

          

        

      

    

    

      

        

          

          

        

      

    

    

      

        

          

          

        

      

    

  

  

    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

- 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

## Why Browser Bridge

Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, and the [Codex extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg) 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 explicit tab sessions rather than ambient browser control.

## Setup

1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser

2. `npm install -g @browserbridge/bbx` - installs the CLI and native host

3. Run `bbx install` (Chromium on Linux, Chrome elsewhere), or target a specific browser with `bbx install --browser chrome`, `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`

4. In the extension side panel, install MCP or CLI (skill) for your agent of choice

5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent

6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)

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 server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.

## 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

- Sessions are tab and origin scoped, auto-refreshed when possible

- All patch operations are reversible and session-scoped

- Structured DOM/style/layout reads are the primary transport; screenshots are a fallback

- Open-ended investigation should start with structured reads on a smaller, lower-cost subagent when the client supports delegation

- The native host daemon auto-starts on demand

## Documentation

- [Quickstart](https://github.com/koltyakov/browser-bridge/blob/main/docs/quickstart.md)

- [Usage scenarios](https://github.com/koltyakov/browser-bridge/blob/main/docs/usage-scenarios.md)

- [Manual setup](https://github.com/koltyakov/browser-bridge/blob/main/docs/manual-setup.md)

- [Agent permissions](https://github.com/koltyakov/browser-bridge/blob/main/docs/agent-permissions.md)

- [CLI guide](https://github.com/koltyakov/browser-bridge/blob/main/docs/cli-guide.md)

- [MCP vs CLI](https://github.com/koltyakov/browser-bridge/blob/main/docs/mcp-vs-cli.md)

- [Troubleshooting](https://github.com/koltyakov/browser-bridge/blob/main/docs/troubleshooting.md)

- [BridgeClient API](https://github.com/koltyakov/browser-bridge/blob/main/docs/api-reference.md)

## Privacy

Browser Bridge itself routes extension data locally through the Chrome extension, native host, and the local client you choose to connect. Browser Bridge does not operate a Browser Bridge cloud service.

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](https://github.com/koltyakov/browser-bridge/blob/main/PRIVACY.md) for the Browser Bridge policy.

## License

MIT. See [LICENSE](https://github.com/koltyakov/browser-bridge/blob/main/LICENSE).