browser-bridge: Instructions file for Codex

Project Guide

Overview

Browser Bridge is a Chrome extension plus local Native Messaging bridge for token-efficient, scoped browser inspection and patching.

Data Flow

Agent/IDE ──stdio──▶ Go MCP Server ──▶ Go client ── JSON-lines over TCP/socket ──▶ Go daemon
bbx Go CLI ─────────────────────────▶ Go client ── JSON-lines over TCP/socket ────┘

Extension Background ── Chrome Native Messaging ──▶ Native Host (relay) ── TCP/socket ──▶ Daemon
(Service Worker) ───── chrome.tabs.sendMessage ───▶ Content Script ───────▶ Browser DOM
                 ├──── chrome.debugger (CDP)
                 └──── chrome.scripting (MAIN world) ─────────────────────▶ Element/patch registries

Outbound: Agent calls MCP tool → Go client sends { type: 'agent.request', request } as JSON-lines over TCP/socket → Daemon routes to extension socket → Native host relays to Chrome native messaging → Background service worker dispatches to content script or handles directly.

Inbound: Content script returns result → Background wraps into createSuccess/createFailure → Native host relays to daemon → Daemon matches pending request → { type: 'agent.response', response } back to agent socket.

Two transport segments:

• Agent ↔ Daemon: Unix domain socket, TCP (default Windows endpoint 127.0.0.1:9223), or Windows named pipe for an isolated bridge home; newline-delimited JSON.
• Extension ↔ Daemon: Chrome Native Messaging (4-byte LE length-prefixed binary) over stdio, relayed by the native-host subprocess.

Package Map

The runtime is a root Go module (go.mod). cmd/bbx is its executable; internal/bridge implements the CLI, native host, daemon, MCP server, and local setup services. Only the extension and npm launcher live under packages/. The published npm module is a bootstrap and launcher under packages/npm, with zero runtime npm dependencies. It does not export a JavaScript client library.

protocol/types.ts is the canonical wire type source; protocol/mcp-tools.json owns MCP tool metadata. make generate-protocol generates Go bindings, JSON Schema, the native runtime catalog, and embedded skills. Generated files are checked in and verified with make check-protocol; do not edit them by hand. Shared TypeScript helpers under protocol/src/ support the browser and build tooling, not a second runtime.