← All guides

Browsers

Chromium browser panes with per-workspace session isolation and a surface masters can drive over MCP.

Conceptual illustration of separate sculptural windows and a magnifying lens inspecting a folded blue form.
AI-generated editorial illustration.
In this guide

A browser pane is a real Chromium webview on the canvas — load a staging URL, read docs alongside your code, or let a master drive it over MCP.

What you get

  • A full Chromium webview with back / forward / refresh and DevTools.
  • Per-workspace session isolation — cookies and storage are partitioned by the space's project folder, so logging into staging in one project doesn't leak credentials into another.
  • A URL bar and standard navigation.
  • A DevTools toggle for inspecting the page directly inside the pane.

Spawn one with Cmd7Ctrl7, or via the spawn menu.

Two separate project containers, each with its own browser session. No connection joins their cookies or storage.

Browser cookies and storage are partitioned by project folder. The two project sessions shown here stay separate.

Diagram by AgentGrid

Canvas and page gestures

Canvas pan, wheel, and zoom continue to work while the pointer is over a browser pane, even when the embedded page has focus. This keeps a browser from becoming a dead zone in a large workspace.

Hold the browser-zoom override when you intend to zoom the rendered page instead of the canvas:

PlatformPage zoom override
macOSHold CtrlCtrl while pinching or scrolling
Windows / LinuxHold AltAlt while pinching or scrolling

CmdFCtrlF opens an in-pane search bar over the browser pane, the same as Cmd+F in Chrome. AgentGrid relays the chord and canvas gestures from the embedded page back to the host, so search, canvas zoom, and canvas pan work whether or not the page has focus.

Screenshot retention

Screenshots taken with screenshot_browser are stored under the project's .agent-grid/screenshots/ folder. Settings -> Browsers controls how long they remain on disk:

  • The default is 30 days.
  • Older files are pruned on the next capture.
  • Set retention to 0 to keep screenshots indefinitely and disable pruning.

DevTools

Each browser pane has a DevTools toggle in its header. Open it for a per-pane Chromium inspector — the same Elements / Console / Network experience you'd get in Chrome. The DevTools window is tied to that specific pane, so multiple browser panes can have their own inspectors open at the same time.

Browser panes the orchestrator drives

A master orchestrator can spawn an "observable" browser pane via the spawn_browser MCP tool — a full webview the user can see and interact with, parented to the master. Useful for showing a staging build together, walking through rendered docs, or fronting a dashboard.

From the master's side the surface is small and focused:

  • spawn_browser({ url, customTitle?, cwd? }) — open at a URL.
  • read_browser({ paneId }) — pull the live URL, title, and a plain-text content extraction (≤ 100 KB).
  • navigate_browser({ paneId, url }) — push the same pane forward instead of opening another.
  • wait_for_browser_navigation({ paneId, timeoutMs, sinceCount? }) — block until the user (or the master) navigates.
  • screenshot_browser({ paneId }) — capture the visible viewport.
  • kill_browser({ paneId }) — close it.

Agents can also drive a pane themselves — on panes they spawned, or panes you attached to them. A brief "Agent: …" label on the pane shows each action:

  • browser_navigate, browser_back, browser_forward, browser_reload — move through pages.

  • browser_read_page — the page as compact text with element refs (e12), paged for long pages.

  • browser_scroll — by direction, to a position, or to an element.

  • browser_click, browser_type, browser_press_key — click controls and enter text. Password entry is refused; enter credentials yourself.

  • browser_wait_for — wait for page text or a CSS selector.

  • browser_evaluate — run JavaScript after you enable Settings → Advanced → Let agents run JavaScript in browser panes. It is off by default; scripts can use the page's signed-in session.

  • browser_screenshot({ paneId, fullPage?, ref?, selector? }) — the viewport, an element, or up to 8,000 pixels of page height.

Capture a particular element with browser_screenshot({paneId, ref}) or a CSS selector; it must fit the viewport. Element capture restores scrolling and takes precedence over fullPage. Click tools accept visible text even when it has no interactive accessible name.

The Coordinator must first call browser_attach for a browser in its scope. That grant lasts for the current turn; attach again on a later turn. Each action rechecks the grant and scope, and uses the same input guards and JavaScript setting.

Workers inherit their team lead's live pane associations and can drive those browser panes too. They cannot attach panes themselves.

The pane is auto-killed when the master pane closes, so you don't need to clean up on shutdown.