Browsers

A browser pane is a real Chromium webview on the canvas — load a staging URL, read docs alongside your code, or hand it to a browser_qa worker for visual end-to-end testing.

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 Cmd+7Ctrl+7, or via the spawn menu.

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:

In-pane search

Cmd+FCtrl+F 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.

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

The browser_qa worker surface

The browser_qa role is the heavyweight browser-driven worker. It gets:

• A real Chromium WebContentsView the user can watch live.
• Playwright MCP (@playwright/mcp) wired in — browser_navigate, browser_click, browser_fill_form, browser_snapshot, and the rest of the Playwright tool surface.
• The AgentGrid browser MCP — wait_for_user_input, request_user_login, highlight_element, save_recording, submit_findings.
• Write access restricted to .agent-grid/qa-specs/ (advisory contract; reinforced in the role's system prompt).

You spawn one with spawn_role({ role: "browser_qa", prompt: "Verify the sign-in flow on http://localhost:3000" }). The worker walks the flow in the visible browser, describes what it sees, and calls submit_findings with a structured report when it's done. Saved regression specs land in .agent-grid/qa-specs/.

Related

• Orchestrating agents — how to spawn and gate on workers, including browser_qa.
• MCP and integrations — the full master tool surface.
• Reference → Keyboard shortcuts — pinch-zoom and canvas gating.