agentleFS
soulmachinesoulmachine/skills/chrome-cdp-setup/SKILL.md

chrome-cdp-setup

Skill3 starsChanged yesterdayMITView on GitHub

Set up Google Chrome on macOS to always launch with the Chrome DevTools Protocol enabled (127.0.0.1:9222) via a Dock launcher app, so local AI agents (Playwright, Puppeteer, browser-use, OpenClaw) can drive the real logged-in browser with no per-connection approval prompt. Use when the user wants to enable a CDP/remote-debugging port for Chrome, pick between the flag, chrome://inspect, and extension routes, connect an agent to Chrome, test a CDP connection, diagnose a 404 from /json/version or an "Allow remote debugging?" dialog, or troubleshoot/revert an existing Chrome-CDP Dock setup.

  • Installs packages

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run scripts/setup_chrome_cdp.sh [port].

    line 46
  2. Distinctive:

    Always start Chrome from the Dock icon.

    line 88
  3. Distinctive:

    Never run both instances at once (session divergence, duplicate extension connections).

    line 98

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Chrome CDP Setup (macOS Dock launcher)

Makes the Dock's Chrome icon launch Chrome with --remote-debugging-port so any local agent can connect over CDP. Chrome 136+ ignores that flag on the default profile directory, and the Chrome 144+ chrome://inspect toggle that does work there makes a human approve every connection — so the launcher points Chrome at a one-time APFS clone of the real profile. All logins, bookmarks, and extensions carry over at near-zero disk cost, the flags take precedence over the toggle, and nothing ever prompts.

Scripts live in this skill's scripts/ dir; run them with absolute paths (~/.claude/skills/chrome-cdp-setup/scripts/...).

Which route

NeedRoute
Unattended agent loop, headless, CI, several tools sharing one browserThis skill: flags + a separate --user-data-dir, launched from the Dock wrapper. No prompts.
Real default profile, human at the keyboard, occasionalchrome://inspect/#remote-debugging toggle, then PLAYWRIGHT_MCP_CDP_TIMEOUT=0 playwright-cli attach --cdp=chrome; the human clicks Allow once per connection. See REFERENCE.md "Approval mode".
Real default profile, one tab, no Chrome promptplaywright-cli attach --extension=chrome (Playwright extension). Per-tab access; its own approval popup takes a shared token via PLAYWRIGHT_MCP_EXTENSION_TOKEN.
Real default profile, whole browser, no promptNot possible in Chrome 136+. The profile clone is the closest thing.

Quick start

scripts/setup_chrome_cdp.sh              # full setup (default port 9222)
scripts/set_default_browser.sh           # optional: make it the default browser — one macOS dialog to click (--revert undoes it)
scripts/verify_cdp.sh                    # signals + one-line verdict naming the state and the fix
uv run --with playwright python scripts/cdp_agent_test.py   # external-agent smoke test

The Dock tile stays named "Google Chrome CDP" while Chrome runs, because the launcher execs Chrome and keeps the app identity. One consequence: macOS attributes Chrome's own writes to the wrapper, so grant it App Management (System Settings ▸ Privacy & Security) or Chrome's auto-update stays blocked. See REFERENCE.md "Which app is running".

Setup workflow

  1. Preflight: confirm /Applications/Google Chrome.app exists, /Applications is writable and Command Line Tools are installed (xcode-select -p); note profile size with du -sh ~/Library/Application\ Support/Google/Chrome.
  2. Run scripts/setup_chrome_cdp.sh [port]. It is idempotent and:
    • quits Chrome cleanly and stops if anything still holds the port — flag mode binds it with no fallback. Open tabs come back on relaunch only if the profile restores the last session; otherwise they are one ⌘⇧T away (REFERENCE.md)
    • clones ~/Library/Application Support/Google/Chrome → Chrome-CDP (cp -Rc; skipped if the clone already exists)
    • builds /Applications/Google Chrome CDP.app: a compiled stub that execs Chrome with the flags, Chrome's icon, ad-hoc signed. Compiled because SIP refuses a script executable; exec because that keeps the Dock tile named Google Chrome CDP (REFERENCE.md "Wrapper app anatomy")
    • pins --profile-directory to the clone's last-used profile, so a multi-profile clone opens that profile instead of the picker — the picker leaves CDP with no default browser context and Playwright's connect_over_cdp fails at attach
    • swaps the Dock's Chrome tile for the wrapper (Dock prefs backed up first) and restarts the Dock
    • launches the wrapper, waits for http://127.0.0.1:<port>/json/version, and on Apple Silicon checks that Chrome came up native rather than under Rosetta
  3. Confirm with scripts/verify_cdp.sh [port] — the last line must read OK. Any other verdict (APPROVAL MODE, PORT STOLEN, PORT TAKEN, NOT LISTENING, DOWN, UNHEALTHY) names the fix, and the exit status is 1.
  4. Prove end-to-end with cdp_agent_test.py — it connects from an independent process, lists the real tabs, opens its own tab, rewrites the DOM, screenshots, and disconnects leaving Chrome running.

Connecting agents

  • Playwright: chromium.connect_over_cdp("http://127.0.0.1:9222")
  • Puppeteer: puppeteer.connect({ browserURL: "http://127.0.0.1:9222" })
  • playwright-cli: playwright-cli attach --cdp=http://127.0.0.1:9222. Not --cdp=chrome: that reads the default profile's DevToolsActivePort and cannot reach the wrapper.
  • Raw WS: re-fetch webSocketDebuggerUrl from /json/version each launch (it rotates).
  • Python agents need only pip install playwright or uv run --with playwright — no playwright install browser download, since they attach to the running Chrome.
  • Browser context management is not supported. at attach means Chrome is sitting on the profile picker — see REFERENCE.md "Profile picker".
  • A first attach to a browser that has been up for hours with dozens of tabs can exceed Playwright's 30 s connect timeout: it attaches to every target, and idle renderers answer slowly. Raise the timeout (PLAYWRIGHT_MCP_CDP_TIMEOUT for playwright-cli) or retry once; the retry is fast.

Rules that prevent breakage

  • Always start Chrome from the Dock icon. Spotlight, or a link click while Chrome is closed, launches the non-CDP default-profile instance — quit it and relaunch from the Dock. With the chrome://inspect toggle on, that instance also grabs port 9222 in approval mode: /json/version answers 404 and every connection prompts. verify_cdp.sh names this state. set_default_browser.sh takes the link click off that list by making the wrapper the default browser (one macOS consent dialog).
  • Chrome's own "Relaunch to update" keeps the flags, so CDP stays up, but the process comes back as Google Chrome.app: a second Dock tile until the next quit, and the Dock tile then no longer names the wrapper. Quit and relaunch from the Dock when convenient (REFERENCE.md "Which app is running").
  • Never run both instances at once (session divergence, duplicate extension connections).
  • The CDP server takes a few seconds after launch: poll with curl --retry 30 --retry-delay 1 --retry-all-errors.
  • The active profile may be Profile N, not Default — read profile.last_used from the clone's Local State before asserting the clone is broken.
  • Loopback only: never add --remote-debugging-address. Any local process can drive the browser and read that profile's cookies — the machine is the trust boundary.
  • On Apple Silicon, confirm the running Chrome shows Arch=ARM64 (lsappinfo info -app com.google.Chrome | grep -io 'Arch=[a-z0-9_]*'; older macOS prints it lowercase). A stale LaunchServices record for the wrapper can silently run the whole browser under Rosetta at several times the CPU cost — see "Rosetta trap" in REFERENCE.md.

Details

Gotchas, approval mode, the Rosetta trap, raw-CDP notes, and revert steps: see REFERENCE.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.