browserbuddy CLAUDE.md

BrowserBuddy

BrowserBuddy 0.2.1 is a shared browser for you and your coding agent: a cross-browser MV3 WebExtension (Chrome and Firefox, one codebase) paired with a Node.js server that serves 25 MCP tools. By default the browser starts the server: the extension calls connectNative, the browser spawns native-host-bin.js, and that host serves Streamable-HTTP MCP on a stable loopback port behind a bearer token it publishes in mcp-endpoint.json — set up with browserbuddy install-host, attached with browserbuddy client-config. The older carrier (browserbuddy serve: MCP stdio server plus a WebSocket hub on 127.0.0.1:8590, dialled by the extension) still works and is selected by the TRANSPORT constant in background.js. The agent acts through the tools and observes the user's own clicks, typing, navigation and downloads as a queryable event log — the same window, the same session, no debug port and no automation flags. Node 22+, no build step, no transpiler.

Component map

• extension/ — the WebExtension, loaded unpacked (Chrome) or as a temporary add-on (Firefox).
  • manifest.json — MV3 manifest; declares both background entry points (service worker for Chrome, event page for Firefox) and strict_min_version 128 for Firefox.
  • background.js — transport selection (TRANSPORT, native by default), reconnect ladder, browser-level observation (tabs, navigation, downloads), RPC dispatch, badge state. The WebSocket client is still here, dormant, reached only when TRANSPORT is websocket.
  • transport-native.js — the connectNative transport. Shares the background global scope (Chrome importScripts, Firefox background.scripts); surfaces a precise hard error naming the host and both expected manifest paths when the host cannot be spawned.
  • content.js — injected into pages: DOM observation, selector construction, redaction, and the page-level half of the RPC surface.
• server/src/ — the Node process.
  • index.js — browserbuddy bin entry point; runs the CLI and reports fatal errors on stderr.
  • cli.js — strictcli app (serve with --port, --data-dir; install-host with --browser, --user-data-dir/--home, --data-dir; client-config), plus startServer which wires hub, store, demos and the MCP server together.
  • client-config.js — the client-config command: reads the live endpoint descriptor and renders the MCP client registration (claude mcp add --transport http … plus an mcpServers block), or hard-errors with the whole setup order. --apply runs the registration; printing is the default. The CLI's only stdout writer.
  • hub.js — WebSocket server: one extension connection at a time, RPC request/response correlation with timeouts, event fan-out.
  • rpc-peer.js — PendingRpcs, the one in-flight RPC table both transports use.
  • native-host-bin.js — the executable the browser spawns via connectNative. Deliberately not a strictcli app: the browser appends its own arguments. Hands fd 1 to the framing channel and points the process stdout stream at stderr.
  • native-messaging.js — the browser's wire framing: 32-bit little-endian length + UTF-8 JSON, incremental decoder, and the per-direction size caps (host → browser just under 1 MB, browser → host 128 MB).
  • native-hub.js — the Hub interface (isConnected/rpc/event) over the native pipe, so mcp.js is transport-blind.
  • http-mcp.js — Streamable-HTTP MCP on an ephemeral loopback port behind a bearer token; one MCP session per initialize.
  • endpoint-file.js — atomic, mode-0600 mcp-endpoint.json (the live url and token an MCP client dials, validated against the host's pid on read) and endpoint-state.json (the token and port the next host respawn reuses).
  • host-manifest.js — Chrome/Firefox native-messaging host manifests, the launcher script, and the Chrome-id-from-key derivation.
  • install-host.js — the one implementation of the host install (manifest + launcher, platform-default profile discovery, Linux-only guard), used by both browserbuddy install-host and scripts/install-native-host.mjs.
  • store.js — event store: 1000-entry ring buffer, per-UTC-day JSONL append, query and waitFor (the lockstep primitive).
  • mcp.js — the MCP tool surface: 18 acting, 3 observing, 4 learning tools, with zod schemas.
  • demos.js — demonstration recorder: captures user events while recording, cleans them into a replayable step list, persists one JSON file per demo.
  • version.js — the one place the server learns its version: it reads package.json, which is what the release bump edits. cli.js, mcp.js, hub.js and native-hub.js all import it instead of holding a literal.
• server/test/ — node --test suite, including a fake extension driver (fake-extension.js) for hub/MCP tests and a fake browser (fake-native-extension.js) that spawns the real host over real pipes.
• scripts/e2e-smoke.mjs — live end-to-end smoke test of the WebSocket carrier against a real browser with the real extension.
• scripts/spike-nativemsg.mjs — live end-to-end proof of the native-messaging carrier on both browsers: installs the host manifest into a throwaway Chromium profile or a throwaway HOME, lets the browser spawn the host, then drives the MCP tools over HTTP. --browser firefox installs extension/ as a temporary add-on over the remote debugging protocol.
• scripts/firefox-harness.mjs — the shared Firefox half of both live harnesses: profile prefs (including the originControls.grantByDefault that stands in for the human permission grant), the launch, and the RDP client that installs a temporary add-on.
• scripts/check-manifest-version.mjs — the version-drift guardrail: fails when extension/manifest.json and package.json disagree. Registered as the manifest-version-lockstep external check in .rlsbl/config.json (tag preflight), so it runs under rlsbl check --all and blocks a release.
• scripts/install-native-host.mjs — development CLI over server/src/install-host.js: writes the host manifest and launcher for a named Chromium user-data-dir or Firefox HOME. End users run browserbuddy install-host --browser chrome|firefox instead.
• docs/ — PROTOCOL.md (normative wire contract) and ARCHITECTURE.md (components, data flow, rationale), both hand-maintained; _README.md and _CLAUDE.md are the selfdoc templates for the root files.
• pypi/ — PyPI name-reservation placeholder package only. Not the product; do not grow it.