browser-bridge AGENTS.md

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──▶ MCP Server ──▶ BridgeClient ── JSON-lines over TCP/socket ──▶ Daemon
bbx CLI ─────────────────────────▶ BridgeClient ── 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 → BridgeClient 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: TCP (127.0.0.1:9223) or Unix domain socket, newline-delimited JSON.
• Extension ↔ Daemon: Chrome Native Messaging (4-byte LE length-prefixed binary) over stdio, relayed by the native-host subprocess.

Package Map

Package	Entry	Responsibility
packages/protocol/	src/index.js	Shared types, error codes, method registry, defaults, budget presets. All other packages import from here.
packages/native-host/	src/daemon.js	BridgeDaemon - TCP/socket server, request routing, pending request tracking with timeouts. src/native-host.js relays between Chrome native messaging and daemon socket.
packages/agent-client/	src/client.js	BridgeClient - connects to daemon, sends requests, tracks responses. src/cli.js is the bbx CLI.
packages/mcp-server/	src/server.js	MCP stdio server (tool schemas). src/handlers-*.js map tool calls to bridge requests.
packages/extension/	src/background.js	MV3 service worker - native port, request dispatch, state management. src/content-script.js handles all DOM operations.