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
In this repository31 other files it gives its agents.
- affix-domainsSkill
- apple-designSkill
- apwcli-pairSkill
- ask-always-on-agentSkill
- asus-esc8000-firmware-upgradeSkill
- asus-esc8000-gpu-bios-tuningSkill
- build-stealth-rustdeskSkill
- cua-macos-lume-sandboxSkill
- deploy-kimi-k26-on-rtx-pro-6000Skill
- deploy-kimi-k3-on-rtx-pro-6000Skill
- deploy-stealth-rustdeskSkill
- ghostty-terminfoSkill
- herdr-rename-hookSkill
- imsg-permissionsSkill
- llm-inference-benchmarkSkill
- lxd-docker-firewall-conflictSkill
- mac-mini-as-headless-serverSkill
- macos-app-multi-instancesSkill
- macos-smb-serverSkill
- mac-smb-automountSkill
- openclaw-diagnoseSkill
- paseo-profilesSkill
- private-fork-syncSkill
- refresh-claude-accountSkill
- ssh-claude-authSkill
- sync-claude-accountsSkill
- to-featuresSkill
- trusted-publishSkill
- ubuntu-lxd-gpu-serverSkill
- ubuntu-nvidia-gpu-enablementSkill
- ubuntu-zfs-mirror-installSkill
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
- Very specific: line 46
Run scripts/setup_chrome_cdp.sh [port].
- Distinctive: line 88
Always start Chrome from the Dock icon.
- Distinctive: line 98
Never run both instances at once (session divergence, duplicate extension connections).
≈ “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.
Files
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
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 testThe 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
- Preflight: confirm
/Applications/Google Chrome.appexists,/Applicationsis writable and Command Line Tools are installed (xcode-select -p); note profile size withdu -sh ~/Library/Application\ Support/Google/Chrome. - 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 thatexecs Chrome with the flags, Chrome's icon, ad-hoc signed. Compiled because SIP refuses a script executable;execbecause that keeps the Dock tile named Google Chrome CDP (REFERENCE.md "Wrapper app anatomy") - pins
--profile-directoryto 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'sconnect_over_cdpfails 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
- Confirm with
scripts/verify_cdp.sh [port]— the last line must readOK. Any other verdict (APPROVAL MODE,PORT STOLEN,PORT TAKEN,NOT LISTENING,DOWN,UNHEALTHY) names the fix, and the exit status is 1. - 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'sDevToolsActivePortand cannot reach the wrapper. - Raw WS: re-fetch
webSocketDebuggerUrlfrom/json/versioneach launch (it rotates). - Python agents need only
pip install playwrightoruv run --with playwright— noplaywright installbrowser 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_TIMEOUTfor 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://inspecttoggle on, that instance also grabs port 9222 in approval mode:/json/versionanswers 404 and every connection prompts.verify_cdp.shnames this state.set_default_browser.shtakes 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, notDefault— readprofile.last_usedfrom the clone'sLocal Statebefore 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.
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
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.

