> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browspark.krishm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension mode and developer mode

> What each mode can do, what Chrome blocks for extensions, and how the companion picks between them.

## 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:

| Blocked domain            | Affected tools                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `HeapProfiler`            | `devtools_memory` snapshot, compare, retainers, sampling                                                        |
| `Target`, `Browser`       | `devtools_cdp`, browser-wide operations, worker targets (`devtools_workers` skipWaiting, start, stop, evaluate) |
| `Security`                | `devtools_security` uses the Network domain's security details instead; certificate details are limited         |
| `DOMStorage`, `IndexedDB` | `devtools_storage` reads web storage through page JavaScript instead, which works for the page's own origin     |
| `ServiceWorker`           | registrations, update and unregister go through the page's `navigator.serviceWorker`                            |
| `Animation`, `Media`      | `devtools_emulation animations` list is unavailable                                                             |
| Chrome's own pages        | `chrome://`, extension pages and the Web Store cannot be automated at all                                       |

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](/reference/capability-matrix) is generated with live, non-mutating CDP probes in both modes. `devtools_capabilities` 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.