Skip to main content

​
Extension mode

The extension attaches Chrome’s debugger to a shared tab and forwards DevTools Protocol commands from the companion. The tab stays in your window with your cookies, logins and extensions. You decide which tabs are reachable from the dashboard’s Tabs page. What you get:
  • 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"} 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. Everything 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: no logins, no history, and it does not share tabs with your own Chrome.

​
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. 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 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 by probing every CDP domain live in both modes. Regenerate it with bun run capabilities after upgrading Chrome.