A web browser automation tool that attaches to the Chrome you already use and paints a glowing halo on every page so you know it is driving.

Playwright, Puppeteer, and Selenium each launch a clean browser instance from your node_modules or system PATH. That instance has a blank profile directory, no cookies, no IndexedDB, no Keychain, and no 2FA state. Every script has to re-create sessions at the top, either by replaying a login flow or by loading a persisted storage_state.json that breaks on SSO, WebAuthn, or TOTP. Fazm uses Playwright MCP in extension mode. It installs a Chrome Web Store extension (Playwright MCP Bridge, ID mmlmfjhmonkocbjadbfplnigmagldckm) and attaches to the Chrome you already use, so every site you are already logged into is live on turn one. The exact flag is --extension in acp-bridge/src/index.ts lines 1029 to 1031, passed when PLAYWRIGHT_USE_EXTENSION is true.

An injected DOM subtree with id=fazm-overlay. The source is acp-bridge/browser-overlay-init.js. It paints four glowing radial-gradient wings on the top, bottom, left, and right edges of the viewport, four slow-moving floating blobs in the corners, and a center pill that reads 'Browser controlled by Fazm · Feel free to switch tabs or use other apps' with a spinning indicator. The canvas has z-index 2147483647 (the max signed 32-bit integer, chosen to beat every stacking context a site might use), and pointer-events none, so it never blocks clicks or text selection. The reason for the overlay is trust. A headed browser run that looks identical to your normal browsing invites accidental clicks in the automated tab. A glowing halo plus an explicit pill removes the ambiguity.

Playwright's addInitScript does not work on CDP-attached contexts when running in extension mode, which is how Fazm runs. So scripts/patch-playwright-overlay.cjs patches Playwright's extensionContextFactory.js at npm postinstall. The patch registers DOMContentLoaded and load event listeners on every page the extension exposes, and each one calls page.evaluate with the full overlay script. Because the script is idempotent (it bails early if document.getElementById('fazm-overlay') is truthy), replays on SPA route changes are no-ops. The init-page script path is passed to Playwright MCP as --init-page at acp-bridge/src/index.ts line 1037.

In most cases, no, because the fingerprint presented to the site is the fingerprint of your real Chrome. Same installed extensions, same timezone, same accept-language, same TLS client, same canvas hash, and for any site you were already logged into, a session cookie already approved by the server. Compare this to a Playwright-launched Chromium, which exposes the CDP navigator.webdriver flag by default and has no prior session. The tradeoff is that you must be willing to let the agent use your real session, which is exactly the reason the overlay exists: it is always visible when automation is active, and the pill invites you to switch tabs so you can keep working.

Four phases, tracked in BrowserExtensionSetup.swift at enum Phase (welcome, connect, verify, done). One, the welcome screen explains browser access. Two, the connect screen shows four sub-steps: install Google Chrome (with a polling timer that detects when Chrome appears on disk), install the Playwright MCP Bridge extension from the Chrome Web Store (another polling timer that detects the extension's status page URL), click the extension popup in Chrome and copy the token shown, paste the token into Fazm. Three, verify runs a live connection test by asking the ChatProvider to issue a browser_snapshot. Four, done flips a flag and the window closes. The extension URL is chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm.

2147483647 is 2^31 minus 1, the largest signed 32-bit integer. Some sites (ad frames, chat widgets, cookie consent banners) set z-index values up to a few million to make sure they paint on top. Using the absolute max guarantees Fazm's halo and pill win the stacking contest on every page without adding runtime overhead. The z-index is set inline on #fazm-canvas2 in the <style> block embedded in browser-overlay-init.js, so it takes effect before any external stylesheet loads.

Playwright MCP saves all snapshots to /tmp/playwright-mcp (set via --output-dir in acp-bridge/src/index.ts:1033). Retina Macs produce images larger than 2000px on the longest edge, which hits Claude's multi-image dimension limit. A Node watcher started at acp-bridge/src/index.ts:710-713 waits for new PNGs and sharp-resizes them in place if they exceed 1920px, then forwards them to the agent. You get sharp screenshots without model errors.

No. Fazm bundles five built-in MCP servers (acp-bridge/src/index.ts:1266): fazm_tools (skill runner and local identity store), playwright (the one this guide is about), macos-use (native macOS accessibility API automation for any Mac app, not just the browser), whatsapp (desktop WhatsApp via a dedicated process), and google-workspace (Drive, Calendar, Gmail). The browser is the most public surface, but in a typical session the agent will chain playwright calls with macos-use calls inside the same turn.

The agent sends whatever snapshot and screenshots it chose to the model you selected (Anthropic Claude by default, or your own OpenAI or local Ollama endpoint). Fazm itself does not upload browser data anywhere separate from that. The extension token, the env vars, and the Playwright process all run locally. The /tmp/playwright-mcp screenshot directory is a local path. Raw DOM never leaves your machine unless the agent chose to include it in a tool-call argument that the model reads.

Yes. That is what the pill text explicitly invites: 'Browser controlled by Fazm · Feel free to switch tabs or use other apps'. Playwright's CDP connection is pinned to a specific page object, so it does not depend on that tab being in the foreground. And the overlay is pointer-events: none, so if you do come back to the automated tab, you can interact with the page underneath (at your own risk of racing with the agent). macOS focus and Mission Control still work normally.

Playwright handles iframes with the browser_snapshot call returning nested frames, each with its own [ref=eN] tokens. The agent reads the outer snapshot, picks the iframe, and calls browser_snapshot on it if needed. For closed Shadow DOM, the snapshot does not descend past the shadow root, so the agent typically switches to accessibility-tree reads on the parent element, or the macos-use MCP server reads the underlying AXUIElement. The overlay appends to documentElement, so it sits above the page regardless of iframe depth or shadow trees.

Upstream. It is the Playwright MCP Bridge extension published by Microsoft, the same company that maintains Playwright. Fazm bundles Playwright MCP (the @playwright/mcp npm package) and wires it to the extension via the --extension flag. That means the CDP attachment path is the same one Playwright's maintainers ship, and security updates to the extension roll out through the Chrome Web Store.