---
name: chrome-cdp-setup
description: 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.
---

# 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

| Need | Route |
|---|---|
| Unattended agent loop, headless, CI, several tools sharing one browser | **This skill**: flags + a separate `--user-data-dir`, launched from the Dock wrapper. No prompts. |
| Real default profile, human at the keyboard, occasional | `chrome://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 prompt | `playwright-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 prompt | Not possible in Chrome 136+. The profile clone is the closest thing. |

## Quick start

```bash
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](REFERENCE.md).