Skip to main content

​
Extension mode

The extension works in Chromium-based browsers, including Chrome, Brave and Edge, and in Firefox or Zen using a separate Firefox build. Tabs stay in your window with your cookies and logins. You decide which tabs are reachable from the dashboard’s Tabs page. Chromium uses its debugger API. Firefox 153+ uses WebExtension APIs and sandboxed user scripts, with extension-specific limits. It needs no remote debugging port to share existing tabs. Several browser profiles can connect to the same companion at once. Each keeps its own sharing permissions. browser_status lists each browserId; use that ID when opening a new extension tab. Existing tabs have globally unique tabId values. See using multiple browsers. What Chromium extension mode provides:
  • All browser_* automation tools.
  • Console, network (including mocks, throttling, HAR), sources with source maps and overrides, the full debugger, elements and styles, tracing and CPU profiles, coverage, emulation, accessibility, security, storage, and most service-worker operations.
  • Chrome’s yellow “started debugging this browser” bar while the debugger is attached, which detaches automatically after 30 seconds of inactivity.
What Chrome does not expose to extensions, and therefore what fails in this mode with a clear “needs developer mode” message: Lighthouse also needs developer mode because it drives its own tab through a debugging port.

​
Developer mode

browser_session {action: "launch", userRequested: true} starts a separate Chrome with a persistent profile under ~/.browspark/profile (or ~/.browspark/profiles/<context> for a named context) and connects to it over the DevTools Protocol directly. Every Chrome domain is available, DevTools opens on every tab by default so you can watch, and there is no yellow bar. Those tabs are always usable and appear in browser_tabs with mode dev. It is a different browser profile: it starts without your everyday browser’s logins or history, and then persists its own sessions. Choose browser: "chrome" or "brave" explicitly; "chromium" remains the compatibility default. Pass browser: "firefox" or "zen" to launch a separate session through WebDriver BiDi. The tool names stay the same, but Chrome-specific operations such as raw CDP and Lighthouse are unavailable. These developer sessions work without the shared-tab extension and have broader automation support than Firefox extension mode. See Firefox and Zen coverage. Use separate context names to run Chrome, Brave, Firefox and Zen together. When opening a developer tab, select mode: "dev" and its context. When several browsers are available, choose the displayed browser or context explicitly instead of relying on connection order.

​
Which one is used

The agent works in your shared tabs unless a capability needs the developer browser. That rule is enforced in the companion, not just suggested in tool descriptions:
  • With the dashboard’s Developer browser setting on Only when needed (the default), browser_session launch succeeds only if a tool reported a “needs developer mode” failure in the last ten minutes, or if the agent passes userRequested: true because you asked for a developer browser in your own words. Otherwise the launch is refused with a message telling the agent to use your tabs.
  • Always lets the agent launch whenever it wants.
  • Never refuses every launch and tells the agent to ask you to change the setting.
When several extension dashboards are connected, developer launches follow the most restrictive setting: Never, then Only when needed, then Always. Sharing and Stop controls remain specific to each browser profile. When no tab is usable at all, the correct move is to ask you to share one or to open a tab with browser_tabs {action: "new"}, never to spin up a separate browser. The tool descriptions and error messages say exactly that.

​
Capability matrix

The capability matrix is generated with live, non-mutating CDP probes in both Chromium modes; it does not describe Firefox or Zen. devtools_capabilities reports the selected tab’s browser and preserves active emulation, recordings, and request interception. Domains that cannot be checked without changing browser state, such as Media, are marked unprobed, not unsupported. Regenerate the matrix with bun run capabilities after upgrading Chrome.