Skip to main content

​
Requirements

​
One-command setup

The setup script covers everything on this page for the common case: it downloads the extension, lets you choose bun, pnpm or npm to run the companion, writes the MCP config for the agents you pick, and prints the pairing steps.
bash setup.sh --test is a dry run: it prints every command and file it would write without touching anything. The script lives at setup.sh in the repo.

​
The companion

The companion is the MCP server. It is published on npm as browspark-mcp (alias browspark) and runs with a single command, no clone or install step:
From a clone of the repo, bun companion/src/index.ts runs the same code from source. Started by an MCP client it speaks MCP over stdio. On every start it also opens 127.0.0.1:9223 for the extension’s WebSocket bridge, the HTTP MCP endpoint and the live view. If that port is already taken by another companion, the new process becomes a relay to the existing one instead of failing. See Multiple agents.

​
Single-file build

Clients that run MCP servers in a sandbox without access to your source tree (Gemini’s local command option, some IDE sandboxes) can use a compiled binary:
The binary has no dependencies and takes the same flags as the source entry point.

​
Flags and environment

The full list is in the CLI and environment reference.

​
The extension

Download browspark-extension.zip from the latest release, unzip it, then chrome://extensions → Developer mode → Load unpacked → the unzipped folder. This is what the setup script does, into ~/browspark-extension.
The extension asks for five permissions: debugger (drive tabs), tabs (list and open them), storage (settings and the shared list), alarms (idle detach timer) and downloads (report downloads). It has no host permissions and injects nothing into pages on its own.
Only one browser profile should hold the extension at a time. If you move it from Chrome to Brave, remove it from Chrome first. Both would otherwise connect to the same companion and the agent would see tabs from whichever connected last.

​
Pairing

The companion creates a random token in ~/.browspark/token (mode 0600) on first start. The extension must present it to connect. Get it from any of these places:
  • Ask the agent to run browser_status; while unpaired the output includes the token and port.
  • The companion prints it on stderr at startup: browspark: ready on ws://127.0.0.1:9223 (pairing token …).
  • cat ~/.browspark/token.
Enter it under Settings → Companion → Pairing token and click Connect. The extension stores the token in its own chrome.storage.local, so it survives browser restarts. Delete the file to rotate the token; the dashboard then needs the new one.

​
Updating

The companion updates itself: bunx browspark-mcp@latest resolves the newest version each time the client starts it. For the extension:
Then reload the extension on chrome://extensions. The dashboard shows a banner when the extension files on disk are newer than the running service worker, and it shows the companion’s version next to the connection status so you can tell when the two are out of step.