Chrome Cdp Setup

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

Quick start

scripts/setup_chrome_cdp.sh              # full setup (default port 9222)
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

Setup workflow

1. Preflight: confirm /Applications/Google Chrome.app exists and /Applications is writable; 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 (session restores on relaunch) and stops if anything still holds the port — flag mode binds it with no fallback
   • clones ~/Library/Application Support/Google/Chrome → Chrome-CDP (cp -Rc; skipped if the clone already exists)
   • builds /Applications/Google Chrome CDP.app (Chrome's own icon, ad-hoc signed, arch -arm64 on Apple Silicon)
   • 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.
• 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, Chrome's "Relaunch to update", or a link click while Chrome is closed all launch 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.
• 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.