chrome-cdp-skill: give an AI agent access to the Chrome session you already have open

The problem: automation tools start a browser, you already have one

Most browser automation starts by launching a browser. Puppeteer and similar frameworks open a fresh, isolated instance with an empty profile, which means no cookies, no sessions, no logins. If the page you care about sits behind a sign-in wall, the agent has to authenticate first, and that is often the slowest and most fragile part of the whole task.

chrome-cdp-skill takes the opposite position. The README states that it connects to the Chrome you are already running, so the agent sees the tabs you already have open, your logged-in accounts, and the current page state. The listed examples are reading pages you are logged into (Gmail, GitHub, internal tools) and interacting with tabs you are actively working in. The intended reader is someone driving an agent that needs the live session, not a clean one: a support engineer looking at a customer's internal dashboard, or anyone whose workflow depends on a page that cannot easily be re-authenticated from scratch.

How the WebSocket connection and per-tab daemon actually work

There is no Puppeteer and no intermediary process between the agent and Chrome. According to the README, the tool connects directly to Chrome's remote debugging WebSocket. On the first access to a tab, a lightweight background daemon is spawned and holds that session open. Chrome's Allow debugging modal appears once per tab; later commands reuse the daemon silently. Daemons exit on their own after 20 minutes of inactivity.

The daemon is the design decision that separates this project from the alternatives. The README argues that chrome-devtools-mcp reconnects on every command, so the Allow debugging modal can reappear repeatedly and target enumeration times out when many tabs are open. Holding one persistent session per tab means the prompt fires once, and the README claims this is why the tool handles 100+ tabs reliably where Puppeteer-based tools time out during enumeration. Treat that as the author's stated rationale rather than a measured result.

Everything the agent does runs through one CLI. The README lists list, shot, snap, html, eval, nav, net, click, clickxy, type, loadall, evalraw, open and stop. The snap command returns a compact accessibility tree rather than raw DOM, which is the cheaper thing to hand a model, and evalraw passes a raw CDP command through when the wrapper does not cover what you need. Targets are addressed by a unique prefix of the targetId printed by list.

Installing chrome-cdp-skill and taking a first screenshot

The runtime dependency is Node.js 22 or newer and nothing else; the README says no npm install is needed. As a pi skill, installation is a single command pinned to a tag:

pi install git:github.com/pasky/[email protected]

For other agents (the README names Amp, Claude Code and Cursor), you clone or copy the skills/chrome-cdp/ directory into wherever that agent loads skills or context from.

Before any command works, remote debugging has to be on. Open chrome://inspect/#remote-debugging in Chrome and toggle the switch. The CLI auto-detects Chrome, Chromium, Brave, Edge and Vivaldi on macOS, Linux and Windows. If your browser writes DevToolsActivePort somewhere non-standard, the README says to point the CDP_PORT_FILE environment variable at the full path.

Then list your tabs and take a screenshot of one. The target argument is a unique prefix of the targetId that list prints:

scripts/cdp.mjs list
scripts/cdp.mjs shot <target>

The screenshot is written to a runtime directory, and because this is the first access to that tab, Chrome shows its Allow debugging modal. Accept it once. Run shot again on the same tab and the daemon answers without the prompt.

Where it breaks: the Allow prompt, the idle timer and the missing headless mode

The same mechanism that makes the tool convenient also constrains it. Attaching to a live session means the session has to stay open, with a visible Chrome window and a human who can click Allow debugging once per tab. That is a poor fit for CI, for a headless server, or for any task where nobody is sitting in front of the browser. If the workflow needs a browser that starts clean and disappears afterwards, this is the wrong tool.

The 20-minute idle exit is a real boundary rather than a footnote. A daemon that has gone quiet for longer than that is gone, and the next command re-attaches, which means the Allow debugging modal can reappear. Long pauses inside a single agent workflow are exactly the situation where that happens.

The README also does not document rollback, and it does not describe what happens when a tab is closed or navigated underneath a live daemon. The open command is noted as triggering the Allow prompt, so opening tabs is not exempt from the confirmation either. And the tool drives your real profile: an agent that clicks or types in a tab is acting on your logged-in accounts, which is a strictly larger blast radius than a disposable automation profile. The README does not describe a permission model or a dry-run mode for those commands.

Against Puppeteer and chrome-devtools-mcp: session reuse versus clean state

The honest comparison is with Puppeteer and with chrome-devtools-mcp, and the difference is what each one optimises for. Puppeteer gives you a browser you fully control: launch flags, a fresh profile, deterministic starting state, and the ability to run many isolated instances in parallel. That is the right shape for testing and scraping. It is the wrong shape when the value is in the profile that already exists.

chrome-devtools-mcp is closer in intent, but the README's stated difference is connection lifetime. It reconnects on every command, so the Allow debugging modal can reappear repeatedly and target enumeration times out with many tabs open. chrome-cdp-skill keeps one daemon per tab instead. If your tab count is small and the modal does not bother you, the reconnect model is simpler and has less background state to reason about. The per-tab daemon is a bet that session persistence is worth the extra moving parts, and the 20-minute idle exit is the price of not leaking daemons forever.

There is also a protocol-level point worth separating from the tooling. CDP, the Chrome DevTools Protocol, is the interface itself, and several projects speak it. Choosing chrome-cdp-skill is choosing a thin CLI over that protocol with a specific session model, not choosing a different protocol.

Maintenance, packaging and what MIT means here

The repository is not archived, and the last push was on 2026-06-28. The most recent release is v1.1.0, tagged the same day, after v1.0.2 on 2026-03-13. That is a project with two releases this year and a small surface area: package.json lists only skills/ and README.md in files, the package name is pi-chrome-cdp, and the pi key points at ./skills. The only runtime requirement is Node.js 22+, so the upgrade cost is mostly whatever changed in the skills directory between tags.

The licence is MIT. In practical terms that permits commercial use and modification with the licence and copyright notice retained, but it comes with no warranty, and nothing in the repository suggests the author offers support. The README does not describe a versioning policy or a deprecation path, so pinning to a tag, as the install command does with @v1.0.1, is the conservative way to take updates. This is a description of the licence text, not legal advice; check it against your own policy.

Editorial conclusion

Adopt chrome-cdp-skill if your agent's job depends on the state of your own logged-in Chrome, and skip it if you need headless, reproducible, or parallel browser sessions. Before trusting it, run scripts/cdp.mjs list against your normal tab count, confirm the Allow debugging prompt appears only once per tab, and check whether the daemon's 20-minute idle exit fits how you work.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pasky/chrome-cdp-skill on GitHub
4. README
5. Releases