--- name: browser-automation description: Let Claude Code drive a browser with the least friction and the right identity on macOS - pick the rung (no browser > hermetic Playwright launch > your real signed-in Chrome), and for your everyday Chrome use the standing tools instead of hand-rolling a launch - chrome-profile.sh setup/doctor/open/tabs/rotate-token (choose a profile by ACCOUNT EMAIL, Microsoft's Playwright Extension with a stored token for zero-click control, list and close any tab of any profile), the chrome-main auto-connect server, and chrome-debug-port-control.sh for a separate profile on a debug port. when_to_use: TRIGGERS - browser automation, drive Chrome, signed-in Chrome profile, Chrome profile by email, Playwright extension, Playwright MCP, chrome-devtools MCP, autoConnect, chrome://inspect remote debugging, remote debugging port, attach to Chrome, connect_over_cdp, headless Chrome, scrape a page that needs JavaScript, logged-in site automation, Allow remote debugging dialog, Playwright extension connect page, Allow & select, leftover tabs, close tabs, too many tabs, extension token exposed, anti-bot. --- # Browser automation > **Self-Evolving Skill**: This skill improves through use. If a step is wrong, Chrome or an MCP server changed behaviour, or a workaround was needed — fix this file (and `scripts/chrome-profile.sh`) immediately, don't defer. Only update for real, reproducible issues, and never add a real account, profile folder name or token. Procedure here; the mechanics and measurements behind each rule are in [`references/doctrine.md`](references/doctrine.md). Scripts are in this plugin's `scripts/`; resolve the path with `cc-plugin-root chrome-profiles` (or use `~/.claude/plugins/marketplaces/cc-skills/plugins/chrome-profiles/scripts/`). ```bash CP="$(cc-plugin-root chrome-profiles)/scripts/chrome-profile.sh" ``` ## 1. Pick the rung — start at the top | Rung | Mechanism | Use when | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 0. **An API or OAuth token** | the site's API with a scoped, short-lived token from the vault/Keychain | The site has an API for the job. **No browser at all**: the most reliable and the safest identity. | | 1. **No browser, plain HTTP** | `curl` / `httpx` | The page renders server-side. | | 2. **A headless browser, no window** | `agent-browser` by tier (below): Lightpanda, then chrome-headless-shell with a saved login, then a profile copy; or a per-tool, sign-in-once profile on a debug port (`chrome-debug-port-control.sh`) | You need JavaScript and no desktop window. The default for anything unattended. | | 3. **Your real Chrome** | the servers below | Supervised work that needs **your own signed-in session**, or a site that blocks automated browsers. | ### Rung 2: the lightest engine that can do the job (operator decision, 2026-11-07) A machine ran out of memory with many agent sessions and desktop Chrome open. The same five-page agent workload was then measured on every candidate engine, and the operator chose these tiers, all driven by Vercel's [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI: | Tier | Use | Command | Memory | | --- | --- | --- | --- | | 1 | public pages, the default | `agent-browser --session S --engine lightpanda open ` | about 145 MB | | 2 | a login, or a page Lightpanda cannot render | `agent-browser --session S --executable-path [--state ] open `, with Google's [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) headless shell | about 600 MB | | 3 | only when the real profile's cookies or bookmarks are needed | `agent-browser --session S --profile "" open ` (a copy, deleted on close) | about 2.3 GB | - **Close every browser when done:** end every job with `agent-browser close --all`. - **Lightpanda reads, it does not draw:** text, links and structure are right, but its screenshots have no CSS layout, and CJK shows as empty boxes (measured 2026-11-07). Judge how a page *looks* from a tier-2 screenshot. - **Read a saved login file at run time:** it comes from the vault, never from a file left on disk. - **Lightpanda sends usage telemetry by default:** run it through a wrapper that sets `LIGHTPANDA_DISABLE_TELEMETRY=true`. - **Lightpanda reports itself to CDP clients as Chrome 124:** its `Browser.getVersion` answers `"product":"Chrome/124.0.6367.29"` (Lightpanda 1.0.3, measured 2026-11-11), while `navigator.userAgent` reads `Lightpanda/1.0`. agent-browser's "out of date" warning on tier 1 comes from that product string and does not apply. - **On Ubuntu 23.10 and later,** AppArmor's user-namespace restriction stops chrome-headless-shell's sandbox ("No usable sandbox!"). The fix is a one-time root AppArmor profile for the binary, Chromium's documented route ([AppArmor user namespace restrictions](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md): "A slightly safer way is to write an AppArmor profile"); `--no-sandbox` instead disables the protection against hostile pages. - **Avoid a full Chromium for tier-1 work:** a Playwright `chromium.launch()`, `npx playwright screenshot`, the `playwright-throwaway-headless` MCP server or branded Chrome with `--headless` costs tier-3 memory. The itp-hooks `headless-browser-tier-reminder` says so when one starts. ## Who signs in, and how - **Unattended work never runs in your real profile.** It uses rung 0, or a per-tool login file or profile copy (rung 2) that holds only the one site it needs, so a mistake or a hostile page can reach that site and nothing else. This is how the agent platforms do it too (Browserbase _Contexts_, Steel and Kernel _Profiles_). - **Your real profile (rung 3) is for work you are watching or have explicitly asked for.** It acts with every session in that profile at once. - **When a per-tool profile's session expires, refill the login from the Keychain or vault, never by having the AI read or type the password**: ```bash node "$(cc-plugin-root chrome-profiles)/scripts/fill-secret.mjs" --port 9222 --page \ --selector '#password' --keychain : [--submit] # or --vault : ``` It reads the secret inside its own process, types it into exactly one field of exactly one tab, and prints only a character count. It refuses a field too short for the secret (which would silently save a truncated one), an ambiguous selector, or a missing secret. 2FA and passkeys still need a person. ## 2. Before any rung-3 work: run the doctor ```bash bash "$CP" doctor [] ``` It checks: Chrome against the latest stable release (and whether Google is actually offering it to this Mac yet); whether `chrome://inspect` remote debugging is ON; the shape and the target account of every browser MCP server, in `~/.claude.json` (every session) and in the on-demand file `~/.claude/mcp-browser.json` (loaded only with `claude --mcp-config ~/.claude/mcp-browser.json`; when that file exists, `setup` registers there, because Claude Code starts a private copy of every user-scope server in every session and a browser server holds 0.1–0.9 GB); that the email is signed in to **exactly one** profile; that the token is stored; and that no look-alike "Playwright …" extension is standing in for the real one. Fix what it flags before acting. ## 3. Choose the profile by ACCOUNT EMAIL — never by folder name Chrome names profile folders itself (`Default`, `Profile 7`), differently on every machine, and renames them when a profile is rebuilt. A server pinned to a folder name drifts onto a different account without any error. So everything here takes an email and resolves it at the moment of use, refusing if zero or several profiles match. ```bash bash "$CP" resolve # → the folder name, or a clear failure bash "$CP" open # open a page in THAT profile of the running Chrome (no debug flags) ``` ## 4. Set up once, then automate with no clicks ```bash bash "$CP" setup # per account you want automated bash "$CP" setup-main # optional: one server that sees every profile's tabs ``` `setup `: resolves the profile → opens the Chrome Web Store page for Microsoft's **Playwright Extension** in that profile only (you click _Add to Chrome_) → opens the extension's status page, which makes the extension create its token, and reads that token from the profile's own Local Storage (`scripts/extension-token-from-profile.ts`, on a private copy; nothing to paste) → stores it in the login Keychain → a hidden macOS dialog asks for the token only when it cannot be read (`setup` says why) → registers an MCP server (default name `chrome-`) that starts `@playwright/mcp --extension` pinned to that profile. **Restart Claude Code** so the new tools load. | Server | Reaches | Clicks | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chrome-` (from `setup`) | ONE profile, resolved by email at every start | **None**, once the token is stored. With no token or a stale one the extension opens a "… is trying to connect" page that waits for a person; `playwright-mcp` now refuses instead and `doctor` flags drift, so fix it with `setup `, never by clicking _Allow & select_. Chrome shows a "started debugging this browser" bar while attached — leave it | | `chrome-main` (from `setup-main`) | Every profile's tabs in one list. Target a page by opening it with `open ` first, then selecting it; confirm the signed-in account **on the page** before acting | Chrome's **Allow** dialog, once per Claude Code session. It cannot be remembered (by design) | | `playwright-throwaway-headless` (`npx -y @playwright/mcp@latest --headless --isolated`) | Its own throwaway full Chromium, in memory, no window. Prefer `agent-browser` with Lightpanda (rung 2 above) unless a tool needs this MCP server's interface | None | Prefer `chrome-` for unattended work. Use `chrome-main` when you need DevTools-level inspection (network, performance) or a page in a profile you have not set up. ### No restart needed: drive a server from Bash When the server you need is registered on demand (in `~/.claude/mcp-browser.json`) and this session did not load it, do not restart Claude Code. `scripts/mcp-drive.ts` starts it as a stdio process and runs a JSON list of tool calls: ```bash D="$(cc-plugin-root chrome-profiles)/scripts/mcp-drive.ts" bun "$D" ext steps.json # that profile's extension server: stored token, no Allow dialog bun "$D" cdp steps.json # chrome-devtools-mcp --autoConnect: every profile's tabs (Allow once) ``` Each step is `{"tool": "...", "args": {...}, "quiet": true|false, "max": N}`; `quiet` prints only ok/ERROR and a length. In `cdp` mode `{{uid:REGEX}}` and `{{page:REGEX}}` resolve against the last `take_snapshot` / `list_pages` of the same run (page ids are renumbered per connection, so never reuse one from an earlier run). Use `cdp` for a profile that has no extension installed. Two things learned driving it (2026-10-18): - **Every `ext` run attaches to a fresh tab**, so a multi-step form (a wizard, a reveal) must run inside ONE `browser_run_code_unsafe` step with Playwright locators, re-navigating at its start. - **That code runs in a sandbox with no `process` and no dynamic import**, so it cannot hand a secret to a local process. Never return a secret from a step. Write it out of the page as a Blob download, then `vault set --stdin` from the file and `rm -P` it; avoid the clipboard, whose history managers keep a copy. ### Tabs: every run closes what it opened The extension server sees only its own session's tabs, so tabs a run leaves behind are invisible to it and pile up in the operator's Chrome. Three tools, all on Chrome's own AppleScript (no extension, no debug port, no dialog): ```bash bash "$CP" tabs list [--json] [--url-match ] # every tab of every profile: window id, tab id, URL, title bash "$CP" tabs close --id [--id …] [--dry-run] # exact ids only; refuses ids that are not open bash "$CP" tabs close --url-match [--max n] # refuses more than --max matches (default 1) bash "$CP" rotate-token # after a token was exposed: new token, stored, page closed ``` `tabs close` refuses to empty a window unless `--allow-window-close` (closing a profile's last tab closes its window). `mcp-drive.ts` lists tabs before and after every run and closes the ones that appeared on a host named in its steps, plus the extension's connect page; `MCP_DRIVE_NO_SWEEP=1` turns that off. Never hand-write a JSON-RPC client instead of `mcp-drive.ts`: an ad-hoc client closes at most its own tab and leaks the rest. These need a terminal inside the Mac's desktop session (Orca, Terminal). Over ssh they refuse before sending anything, because there the Apple event hangs and macOS shows an Automation prompt on that Mac's screen; never answer such a prompt with Allow. **Saved tab groups (measured 2026-11-17).** Closing tabs is not the whole job. The extension puts each connection's tabs in a group titled "Playwright · ", and closing that group's last tab, which every run does, makes Chrome (131+) **save** the group, synced to every device and never removed: one saved group per run (a controlled run added one; with `--no-tab-group`, none). About 100 had piled up across 10 profiles before the fix. `playwright-mcp` therefore passes `--no-tab-group` (supported since `@playwright/mcp` 0.0.85 and extension 0.5.0); `CHROME_PROFILE_TAB_GROUP=1` restores the group for a supervised session. AppleScript cannot see groups, so `tabs list` never shows this residue: `bash "$CP" saved-groups ` counts what a profile still holds, and `doctor ` flags it. Count with a LevelDB reader (that command does); a byte grep of `Sync Data` also counts deleted groups until compaction (53 by grep against 33 live). Chrome has no API and no bulk delete for saved groups, and deleting through Chrome is what reaches the other devices, so never edit `Sync Data`. Two ways to delete them: **pinned** groups (chips on the bookmarks bar) in the background, by pressing each chip, which reopens the group, then one extension connection after about 30 s idle: the extension's startup cleanup ungroups every open "Playwright…" group, and Chrome deletes an ungrouped saved group. **Unpinned** groups (listed only under ⋮ › Tab groups) need the foreground: ⋮ › Tab groups › the group › Delete group, then confirm "Delete Tab Group?" (absent where its "Don't ask again" was ticked). Chrome's native menus ignore an accessibility press on a submenu item, but the keyboard works (Right, Down to Delete group, Return). ## 5. Things that will bite - **The throwaway server must be headless, isolated and named as such.** Registered as plain `playwright`, it opened a visible, signed-out Chrome window (with an "unsupported command-line flag: --disable-blink-features=AutomationControlled" bar) in every session that called it, and since its tools share names with the signed-in extension servers, sessions wanting your signed-in profile picked it by mistake. `doctor` flags a throwaway registration without `--headless --isolated` or without `throwaway` in its name. - **Install the extension in the target profile only.** Every profile that has it is drivable by anything holding its token. - **A password manager's inline menu can break the extension's connection** (another extension's frame in the page detaches it). Turn off that extension's site access for the sites you automate, or finish that page through `chrome-main`. Measured 2026-10-18 on an email "chips" field in the Google Cloud console: even a scripted `fill` detached it, because the field took focus. What worked without focus: set the value through the element, dispatch `input`, then dispatch a synthetic `keydown` Enter whose `keyCode` is defined as 13. - **Set form values by script rather than synthetic keystrokes** when a field misbehaves; it also stops autofill pop-ups from opening. For a message, fill the whole text once, read the field back and compare it (whitespace-normalised) with the intended text, and only then press Send; clear the field and stop on a mismatch, then confirm the message in the thread afterwards. - **Nobody uses the automated window while a run is going.** A person clicking in that window moves focus and breaks the run. Tell the operator which window is in use (or give the run its own window) before starting. - **Never trust on-page "success" text** for a state change. Re-read the state, and prove the negative. - **Never script a fresh debugging connection per command against your everyday Chrome.** Each new connection through `chrome://inspect` costs the operator one _Allow_ click; a stopgap client that reconnected per call raised about fifteen in one session (2026-10-07). If a profile has no `chrome-` server, run `setup ` for it instead: when the extension is already installed it needs no click and no paste. - **Never retry a login form** on a surprise (captcha, 2FA, odd page): stop and look. - **Secrets never pass through the chat.** Download or read them into the Keychain/vault by script, and print only lengths. - **"Chrome is being controlled by automated test software"** appears only on browsers that automation _launched_ (rung 2); your everyday Chrome never shows it. ## 6. A separate profile on a debug port (no Allow dialog, not your logins) For a sign-in-once automation profile that never touches your everyday Chrome: ```bash P="$(cc-plugin-root chrome-profiles)/scripts/chrome-debug-port-control.sh" bash "$P" up # port 9222, profile ~/.local/share/chrome-debug-profile (CHROME_DEBUG_PROFILE / CHROME_DEBUG_PORT to change) bash "$P" status # reports the profile ACTUALLY attached bash "$P" down # always, when done — an open port lets any local process read that profile's cookies ``` It refuses the default Chrome folder, because Chrome 136+ silently ignores `--remote-debugging-port` there. Connect with `--browser-url=http://127.0.0.1:9222` or `connect_over_cdp`. Never bind the port beyond loopback. ## Post-Execution Reflection After this skill completes, check before closing: 1. **Did `doctor` agree with what actually happened?** If a server connected to the wrong account, or a check passed while the route failed, fix the check in `chrome-profile.sh`. 2. **Did any click or dialog appear that this skill said would not?** Record the Chrome or extension version and the cause in `references/doctrine.md`. 3. **Did a secret pass through the conversation?** If so, rotate it and fix the step that exposed it. Only update if the issue is real and reproducible — not speculative.