zero-bridge

Let your local AI agents — pi, Claude Code, Codex, anything that speaks MCP — drive a real Chrome tab: navigate, read the page, click, type, screenshot, scroll, run JS. Your real browser, your real session, your real fingerprint.

• Loopback-only (127.0.0.1) + shared-secret pairing. Nothing off-box can reach it.
• Uses chrome.tabs + chrome.scripting only — no chrome.debugger, so there's no "X is debugging this browser" banner.
• The agent surface is a tiny MCP stdio server (zero deps beyond ws on the sidecar). The extension is a dumb arm; all decisions live in the agent.

Standalone fork of the CeroSpace Bridge, repackaged as a self-contained npm CLI.

Architecture

agent ──HTTP /api/browser/rpc──▶ sidecar ◀──WS /api/browser/agent── Chrome extension ──▶ tab
        (mcp-server.js)          (server.js)                         (extension/)

Install

npm i -g @gonrocca/zero-bridge
# or run without installing:
npx @gonrocca/zero-bridge

Quick start

1. Start the sidecar (leave it running):

   zero-bridge

2. Set up the extension — open the guided page it prints:

   http://127.0.0.1:1456/browser

   • Option A (one click): "Abrir Chrome con el bridge cargado" launches a dedicated Chrome profile with the extension preloaded.
   • Option B (manual): open chrome://extensions, enable Developer mode, Load unpacked → pick the extension/ folder the page shows you.
   • Then click the zero-bridge icon in Chrome, paste the WebSocket URL and token from the page, hit Save & connect (dot turns green), open the tab you want the agent to use and click Attach this tab.
3. Register the MCP with your agent.

pi

pi mcp add browser -- node "$(npm root -g)/@gonrocca/zero-bridge/src/mcp-server.js"

Or in ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/zero-bridge/src/mcp-server.js"]
    }
  }
}

Claude Code

claude mcp add browser -- node "$(npm root -g)/@gonrocca/zero-bridge/src/mcp-server.js"

Tools

browser_status · browser_attach · browser_detach · browser_tabs · browser_activate_tab · browser_open_tab · browser_close_tab · browser_navigate · browser_read · browser_click · browser_type · browser_press · browser_scroll · browser_wait_for · browser_screenshot · browser_back · browser_forward · browser_reload · browser_eval

browser_read returns a numbered list of interactive elements with a ref you pass to browser_click / browser_type — the recommended flow (read → act by ref) instead of guessing CSS selectors.

CLI

zero-bridge [start]   Start the sidecar + setup page
zero-bridge mcp       Run the MCP stdio server (agents spawn this)
zero-bridge setup     Print token, ws url, extension dir, mcp command (JSON)
zero-bridge token     Print the current pairing token
zero-bridge --help

Config (env)

| Var | Default | What | |-----|---------|------| | ZERO_BRIDGE_PORT | 1456 | sidecar port | | ZERO_BRIDGE_TOKEN | (from data dir) | override pairing token |

Token + data live in the OS data dir (~/.local/share/dev.zero.bridge/bridge.json on Linux).

Security

• Everything binds to 127.0.0.1. The extension only talks to this local sidecar.
• The WebSocket requires the pairing token; rotate it from the setup page if leaked.
• The extension has broad host permissions (so it can act on any tab you attach), but it only ever acts on the tab you explicitly attach — and only when the sidecar is running and paired.
• Pages with a strict CSP can block browser_eval (executeScript in MAIN world). Prefer the structured tools.

License

MIT