Chapter 28 — Browser automation

Give your agent a real web browser. thClaws drives a full Chromium through Microsoft’s official Playwright MCP server — the agent navigates, clicks, fills forms, reads pages, and runs JavaScript-heavy sites the way a person would, not by guessing pixel coordinates. You get a Browser tab to watch it work, take over to log in yourself, and hand control back. Built across v0.48–v0.52.

This is the inverse of “computer use” screenshot tools: the agent works from the page’s accessibility tree (fast, reliable, cheap), and can also see the rendered pixels when a page is visual-only.

When to use it (vs. WebFetch)

thClaws already has WebFetch / WebScrape for pulling static pages. Reach for the browser when fetch can’t do the job:

• Logged-in / authenticated sites — you sign in once, the agent works inside your session.
• JavaScript-heavy apps — SPAs, infinite scroll, content that only appears after interaction.
• Forms and flows — multi-step submissions, file uploads, dialogs.
• “Fix this for me” — the 12-gram pattern: you’re stuck on a broken web form, you tell the agent “figure out why Submit is greyed out and send it,” and it reads the HTML, JS, console, and network to do it.

For a one-shot read of a public article, WebFetch is lighter.

Turning it on

Browser automation is on by default since v0.49.2 — every workspace gets it with no configuration, as long as Node.js (npx) is on your PATH (Playwright is a Node package).

To turn it off, or force headed/headless, set it in .thclaws/settings.json:

{
  "browserEnabled": false,        // opt out entirely
  "browserHeadless": true          // force headless even on desktop
}

• Desktop default: headed — a real Chromium window opens beside the app the first time the agent uses a browser tool. You can watch and interact with it directly.
• Cloud default: headless — there’s no window on a runner, so the Browser tab’s live view is your window (see below).

Nothing is downloaded until first use: Chromium launches lazily on the first browser tool call, so an idle workspace pays nothing.

No Node? On a machine without npx, the Browser tab shows a setup hint instead of erroring, and the agent simply runs without browser tools. Install Node.js (e.g. brew install node) and restart.

The Browser tab

When browser automation is enabled, a Browser tab appears. It has three parts:

Status — whether the managed browser is on, headed or headless, the launch command, and a warning if the browser binary can’t be found.

Live view / screenshot — the rendered page:

• On cloud / headless, this is a live screencast (a continuous video-like stream) once you enter takeover, so the headless browser has a real window after all.
• Otherwise it auto-captures a fresh screenshot ~1 second after every browser action, plus a manual 📷 capture button. Visual-only content (canvases, charts) shows here even when the accessibility tree can’t describe it.

Activity feed — every browser_* tool call and result streams in with timestamps, plus live console errors and page navigations (so you can see what the agent — or the page — is doing).

Agent sidebar — a compact chat docked on the right, the same conversation as the Chat tab. Direct the agent without leaving the tab: “log-in is done, take over and export the report.” It accepts slash commands too (/clear, etc.) and stays in sync with the other tabs.

Taking over — log in yourself, then hand back

Some sites you have to log into personally (your bank, LinkedIn). Click 🖱 Take over and the live view becomes a remote control:

• Click anywhere on the page,
• Scroll with your mouse wheel,
• Type into the focused field (with quick Enter / Tab / Esc / ⌫ keys), and
• a URL bar + back button to navigate.

Do your login, then tell the agent in the sidebar to continue. On desktop you can also just use the headed Chromium window directly — the agent shares the same browser, so whatever you do (sign in, accept a cookie banner) is there when it takes over.

Logins persist across restarts

The browser keeps a profile on disk, so cookies and sessions survive browser restarts — and, on cloud, pod restarts and pauses. Log into a site once and the agent stays logged in next time, without you re-authenticating every session.

The profile lives outside your workspace folder, and is explicitly stripped from agent publishing — so your cookies can never leak into an agent you share on the catalog.

Safety notes

• The browser runs with your privileges and (when you’re logged in) your sessions. Treat it like handing the agent your browser: fine for trusted tasks, think twice before pointing it at sensitive accounts unattended.
• Browser tools are mutating — under ask permissions the agent asks before acting; under auto it just goes. See Chapter 5 — Permissions.
• The takeover controls are yours, routed straight to the browser — they don’t go through the agent or cost tokens.

Troubleshooting

Under the hood

For engineers: the engine owns the Chromium process and attaches Playwright MCP to it via a DevTools endpoint, so the agent’s tools and your takeover drive one browser. Full internals — the browser_cdp module, screencast, input, cookie snapshot/restore, and the runner-image packaging — are in the technical manual’s browser.md.