Wire protocol

Defined in shared/protocol.ts (protocol version 3). Transport: a WebSocket from the extension’s background process to ws://127.0.0.1:<port>. Chromium uses a service worker; Firefox uses background scripts. The first message must be hello; anything else, or a frame that is not a JSON object, closes the socket. Connections and requests that carry a web page’s Origin header are refused, so pages in the browser cannot reach the companion. Multiple extension profiles can connect to that port simultaneously. The companion assigns each connection a browserId and translates browser-native tab IDs into public IDs unique across all extension and developer browsers. The extension wire messages below use native tab IDs; MCP tools use public tab IDs. Sharing is checked by the extension that owns the tab.

Message shapes

interface Req { id: number; method: ReqMethod; params?: unknown }   // companion → extension
interface Res { id: number; result?: unknown; error?: string }       // extension → companion
interface Evt { event: EvtName; params?: unknown }                   // either direction

Requests (companion → extension)

Method	Params	Result
`tabs.list`		`TabInfo[]` for every window
`tabs.create`	`{url, active?}`	The new tab, opened in the current window and shared automatically
`tabs.close`	`{tabId}`
`tabs.activate`	`{tabId}`	Brings the tab to the front of its window
`tabs.hold`	`{tabId, hold}`	Keep the debugger attached past the idle timeout (inspection sessions, long operations)
`tabs.prepare`	`{tabId}`	Prepare a shared New Tab for explicit navigation by moving it to `about:blank`
`window.size`	`{tabId, width?, height?}`	Read or set the window size
`downloads.list`		The browser’s download items
`extensions.list`	`{client?}`	`ExtensionInfo[]` of installed extensions (needs the user’s consent and the `management` permission)
`extensions.info`	`{id, client?}`	One `ExtensionInfo`, with `permissionWarnings` where the browser provides them
`extensions.setEnabled`	`{id, enabled, client?}`	The updated `ExtensionInfo`
`extensions.uninstall`	`{id, client?}`	`{uninstalled: true, name}` after the browser’s own confirmation dialog
`extensions.options`	`{id, client?}`	Opens the extension’s options page in a tab: `{id, windowId, url, extensionId, name, automatable}`
`extensions.message`	`{id, message, client?}`	`{reply}` from `runtime.sendMessage(id, message)`: JSON only, at most 1 MB each way, 30 s timeout
`tools.catalog`	`{tools: ToolInfo[], version}`	Stores the catalog for the Tools page
`graph.state`	`ConnectionGraph`	`{received: true}` when accepted; `{received: false}` when this profile disabled Graph
`cdp`	`{tabId, method, params?, sessionId?, client?}`	Result of the DevTools Protocol command on Chromium, or a supported Firefox adapter command. `client` names the agent for the activity log

Events

Event	Direction	Params
`hello`	extension → companion	`{version, extensionVersion, browser?, browserEngine?, userAgent?, instanceId?, browserSessionId?}`
`tabs`	extension → companion	`TabInfo[]` whenever tabs or sharing change
`cdp.event`	extension → companion	`{tabId, method, params, sessionId?}` for every protocol event on an attached tab
`detached`	extension → companion	`{tabId, reason}` when Chrome or the idle timer detaches
`tools.policy`	extension → companion	`{disabled: string[], haveCatalog?: boolean, devMode?: 'auto' \| 'always' \| 'never', overlay?: boolean, graph?: boolean}`
`ping`	extension → companion	Keep-alive every 20 seconds

instanceId is persistent per extension installation; browserSessionId changes when the browser restarts. Together they keep reconnects associated with the right profile without reusing a previous browser run’s public tab IDs. hello.browserEngine is optionally 'chromium' or 'firefox'; an omitted value uses the legacy Chromium default. The Firefox extension declares its engine explicitly.

`ConnectionGraph`

interface ConnectionGraph {
  thisBrowserId: string;
  agents: { id: string; name: string }[];
  browsers: {
    id: string; name: string; mode: 'extension' | 'dev';
    sharedTabs: number; context?: string;
    browserEngine?: 'chromium' | 'firefox';
  }[];
}

The companion sends changed snapshots only to profiles with tools.policy.graph: true. thisBrowserId identifies the receiving extension profile. Agents appear only after MCP initialization. sharedTabs counts shared tabs for an extension profile and open tabs for a developer context. Snapshots contain connection names, IDs and counts, without page URLs, titles, contents or sharing grants. The extension validates unique agent and browser IDs, nonnegative safe-integer tab counts, valid modes and a receiving browser with mode: 'extension'. When present, browserEngine must be 'chromium' or 'firefox'; it is optional so older graph snapshots remain valid without a protocol-version change. The dashboard uses it to choose the Chromium or Firefox logo for an unidentified browser. Node positions and canvas pan/zoom are local dashboard state and do not travel over the wire.

`TabInfo`

interface TabInfo {
  id: number; url: string; title: string;
  shared: boolean; attached: boolean; windowId: number;
  agent?: boolean;        // opened by an agent, shared automatically
  favIconUrl?: string;
  unsupported?: string;   // reason this backend cannot automate the tab
}

The companion adds browserId, browserName and browserEngine to its public tab records. They are not required in extension TabInfo messages. unsupportedReason(url, engine) marks browser-internal schemes, extension pages and the Chrome Web Store. For Firefox it also rejects protected Mozilla sites and non-HTTP(S) pages; about:blank remains available for preparing a tab. isNewTab(url) recognizes supported Chromium New Tab pages and Firefox about:newtab / about:home, which may be shared and navigated but not inspected.

HTTP routes on the same port

Route	Purpose
`GET /`	`browspark companion` health text
`POST/GET/DELETE /mcp`	MCP over Streamable HTTP
`GET /live/:tabId`	Live view page
`GET /live-ws?tab=`	Live view WebSocket: `frame`, `hello`, `error` messages out; `mouse` and `key` messages in

Get started

Connect an agent

Concepts

Dashboard

Guides

Reference

Message shapes

Requests (companion → extension)

Events

`ConnectionGraph`

`TabInfo`

HTTP routes on the same port

​Message shapes

​Requests (companion → extension)

​Events

​ConnectionGraph

​TabInfo

​HTTP routes on the same port

Message shapes

Requests (companion → extension)

Events

`ConnectionGraph`

`TabInfo`

HTTP routes on the same port