Give the agent a real browser (chromium + chrome-devtools-mcp) during runs

[nitedani]

Problem

Right now the agent has no way to actually load a page, inspect the DOM, check console errors, or take a screenshot while it's working. It's flying blind on any frontend/UI task — it can only guess whether a change actually works.

Proposal

Ship a Docker image (or extend the existing sandboxed runner image, see #109) with:

• Chromium pre-installed
• https://github.com/ChromeDevTools/chrome-devtools-mcp pre-installed and wired up as an MCP server available to the agent by default

This would let the agent open the app it's building, click around, read console/network output, screenshot and present results as part of its normal workflow — not just run static type-checks/tests.

Why

Headless browser access during the run (not just in a separate test-writing step) meaningfully improves the agent's ability to verify frontend changes actually work, rather than just compiling/type-checking.

[brillout]

Is there a reason why you don't use Claude's Chrome extension? Or is your proposal about built-in and zero-config support, without the need for a browser extension?

Asking so that we can evaluate the priority. (Agents being able to access the browser is indeed a must-have.)

[suleimansh]

Scoped this. One architectural thing to flag first, then a plan.

The mismatch: the agent (Claude Code) runs on the host via claude -p, in the workspace. The Docker/WebContainer Runner (#109) boots and serves the app (serve-check preview, deploy) — it does not run the agent. So baking chromium + chrome-devtools-mcp into the Runner image only helps if the agent also moves into the sandbox, which isn't how it works today (that's a much bigger change: agent-in-container + Claude auth passthrough + streaming events out).

The good news: Claude Code natively supports MCP (claude --mcp-config <file> / --strict-mcp-config), our driver already has an extraArgs passthrough, and chrome-devtools-mcp is a maintained stdio server (chrome-devtools-mcp@1.5.0). So we can give the agent a browser without touching the Runner at all.

Recommended: phase it.

• Phase 1 (host, unblocked, small): add an mcpServers option to ClaudeCodeDriver -> write a temp MCP config -> claude --mcp-config. Wire chrome-devtools-mcp behind a flag (e.g. --browser). The agent points it at the app's dev-server / preview URL (we already surface an AppPreview), so it can navigate, read console/network, screenshot, and inspect the DOM during the run. Chromium comes from chrome-devtools-mcp's own browser resolution. Delivers the actual capability on a dev machine.
• Phase 2 (sandboxed, follow-up, infra-gated): the Docker-image version you described — but it only pays off once the agent runs inside the Runner. Bundle chromium (alpine needs chromium + fonts + --no-sandbox) + chrome-devtools-mcp into the image, MCP config points at the in-container browser. Bigger, gated on the agent-in-sandbox model + a real Docker env.

Open Q @nitedani: OK to land Phase 1 (host MCP, no Runner change) first, then treat the Docker-image bundling as the Phase 2 isolation story? Or do you specifically want the agent moved into the sandbox as part of this?

[brillout]

Btw. playwright can also take screenshots. So I wonder if a real Chromium UI brings any added value here — I assume, for example, that Claude's Chrome extension takes screenshots and doesn't actually read the screen stream.

[suleimansh]

The added value isn't screenshots, it's the DevTools surface: live console errors, network request/response bodies, DOM/accessibility-tree queries as tool calls mid-run. Playwright and the Chrome extension give a static image the agent has to eyeball. So it's "read the console and network" vs "look at a picture".

And yes, zero-config is the goal: built-in, no browser extension.

I'll land Phase 1 as an opt-in --browser flag to try it out. Host side only, no Runner change: driver writes a temp MCP config and passes --mcp-config, wiring chrome-devtools-mcp against the app preview URL we already surface. Off by default. Phase 2 (chromium in the sandbox image) stays gated on the agent-in-container move.

[brillout]

I see, and in that case that's a major added value indeed.