Skip to main content

​
Shared tabs

An agent can only reach tabs you share. Sharing happens in the dashboard’s Tabs page: share individual tabs, or switch on Share everything to include current and future tabs. Stop or Unshare revokes that tab even with Share everything enabled; explicitly share it again to resume. Per-tab grants and revocations live in chrome.storage.session, so they reset when the browser restarts; Share everything is persistent. Tabs from every connected Chrome, Brave, Firefox or Zen profile count. browser_tabs and browser_status list each tab with its owning browserId and windowId. Public tabId values are unique across all browsers, even if two browsers assign the same native tab number. Sharing and Stop controls remain independent in each profile.

​
Tabs the agent opens

browser_tabs {action: "new", url, browserId} and browser_fetch open ordinary tabs in the selected extension browser’s current window, next to your own. When several extension browsers are connected, use the browserId displayed by browser_status. They are shared automatically and recorded as owned by the agent that opened them. There is no dedicated agent window. Close them with browser_tabs {action: "close", tabId} or yourself; browser_fetch closes its tab when it is done unless keepTab is set. For a separate developer browser, select its context instead. See Using multiple browsers.

​
Choosing the target tab

Page tools take an optional tabId. When it is omitted the companion resolves in this order:
  1. The calling agent’s most recently opened usable tab.
  2. The only usable tab, if there is exactly one.
  3. Otherwise the call fails and lists the usable tabs, asking for an explicit tabId.
“Usable” means shared and not a browser-internal page. chrome://newtab is usable for browser_navigate so an empty tab can be pointed at a website; other chrome://, extension and Web Store pages are reported as unsupported. Developer-mode tabs are always usable.

​
Attaching and the yellow bar

This section applies to Chromium. The Firefox extension uses sandboxed user scripts and does not attach a debugger or show the yellow bar. The extension attaches Chrome’s debugger to a tab the first time a command targets it. Chrome then shows its own “Browspark started debugging this browser” bar; the extension cannot hide it. After 30 seconds without a command the extension detaches and the bar disappears. Exceptions:
  • A running devtools_session keeps the tab attached so console and network collection is not interrupted.
  • An explicit hold from a long-running operation (traces, profiles, waits) does the same.
Change the idle timeout by setting idleDetachMs in the extension’s chrome.storage.local (open the service worker console from chrome://extensions and run chrome.storage.local.set({idleDetachMs: 120000})). To hide the bar entirely start the browser with --silent-debugger-extension-api, for example on macOS after quitting it:

​
The agent overlay

The overlay is available in Chromium and Firefox. On Firefox extension tabs the in-page Stop button is unavailable, so use Stop or Unshare in the dashboard there. While the agent drives a shared tab, the tab shows a soft cyan halo around the page, a compact charcoal pill naming the agent, and a small dark cursor with a gray outline that travels to each element before it is clicked. Travel eases in and out over roughly 0.3–1.2 seconds depending on distance; reduced-motion preferences make it instant. The pill uses the dashboard’s dark palette with a mint status dot. Clicks produce a subtle ring, and fields being typed into get a thin cyan outline. The frame fades a few seconds after the last command and returns on the next one. The pill has a Stop button. Pressing it revokes the tab on the spot, exactly like unsharing it from the dashboard: the debugger detaches, the agent’s next command is refused, and you share the tab again when you want to resume. The overlay uses an isolated script world and a closed shadow root to separate its controls and styles from the page. Stop remains available to screen readers; decorative effects are hidden from them. Agent snapshots and text reads exclude the overlay, and screenshots and PDFs temporarily hide it. It appears on the main frame only, and each profile can switch it off from Settings → Agent overlay. Chromium developer-mode tabs and Firefox extension tabs show the frame and cursor without the Stop button, since there is nothing to unshare there.

​
Activation

Settings → Work in background is on by default in each extension profile. The agent interacts with its assigned tab without activating it. If an operation needs foreground interaction, it reports that requirement. You can select the tab yourself or turn off Work in background for that profile; foreground mode lets input and screenshots activate the target tab.

​
Watching in DevTools

You can open DevTools (F12) on a shared tab while the agent works. Chrome allows both at once; the console, network and debugger panels show what the agent’s tools are doing. What Chrome does not allow is the agent driving the DevTools window itself, so asking it to “open the device toolbar” or “press Cmd+Shift+C” cannot work; the equivalent tools are devtools_emulation and devtools_elements.