Model or dataset
pasky/chrome-cdp-skill avatar
pasky/chrome-cdp-skill

chrome-cdp: a skill that gives an agent your logged-in Chrome, and the port that makes it possible

Give your AI agent access to your live Chrome session — works out of the box, connects to tabs you already have open

3,289 stars203 forksJavaScriptMIT

At a glance

What is it?
Instead of launching its own browser, this skill connects to the Chrome you already have open and keeps a daemon per tab so the debugging prompt appears once. That is what makes it pleasant, and it is also the reason the security decision belongs to you rather than to the agent.
Who is it for?
Use it on a browser profile that is not signed into anything you would mind an agent reading, and turn the remote debugging switch off again when you are done, because the tool is only as contained as that port is. Three things to settle first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 140 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pasky/chrome-cdp-skill3,289 ★ · +32
Star history
Repository2026-09-112026-11-15
pasky/chrome-cdp-skill3.3k3.3k

32 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The documented install command pins a tag behind the current release

The pi install line names a specific version:

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

The package file says 1.1.0, and the release list agrees, with v1.1.0 published on 2026-06-28 after v1.0.2 from 2026-03-13. The default branch was pushed on the same day as the 1.1.0 release. So the command written for the happy path installs the previous tag, and following it verbatim gets a version one release behind the one the repository is currently at. The non-pi route avoids the question entirely: clone or copy the skills/chrome-cdp directory wherever the agent loads skills or context from, which is what the file suggests for Amp, Claude Code and Cursor. That path also avoids any question about which tag a package manager resolved.

The published package is a skills folder and nothing else

The package file has no dependencies, no bin entries and no scripts. What it declares is a name, pi-chrome-cdp, a version, a keyword list for the package index, a licence, and two things that matter:

code
"files": [
    "skills/",
    "README.md"
  ],
  "pi": {
    "skills": [
      "./skills"
    ]
  }

So the npm-shaped artefact is a directory of skill files plus the readme, and the pi field registers that directory as the loadable skill. There is nothing to compile and nothing to resolve, which matches the claim that the only runtime dependency is Node.js 22 or newer and that no install step is needed. The repository itself is five entries deep, a gitignore, a licence, the readme, the package file and skills, meaning the entire implementation lives under that one directory and the command line entry point referenced throughout the readme, scripts/cdp.mjs, is a file inside it.

The toggle you flip is a browser-wide grant, not a per-tool permission

The whole design rests on one switch. Remote debugging is turned on in the browser's own settings page, at chrome://inspect with the remote-debugging fragment, and once it is on, the debugging WebSocket accepts connections. That switch is not scoped to this project and does not know which client is connecting, so the correct reading of the setup step is that you are opening a control interface to a browser that holds your mail, your code host and whatever internal tools you keep signed in. The one gate in that chain is Chrome's own Allow debugging prompt, which appears per tab the first time something attaches. That prompt is the entire authorisation model, and it is a browser-level dialog rather than something the skill checks, scopes or records.

One daemon per tab, and a session left open for twenty minutes

The reason the prompt does not reappear on every command is the part of the design worth understanding. The skill speaks to the remote debugging WebSocket directly, with no Puppeteer and no intermediary process, and on first access to a tab it spawns a small background daemon that holds that session open. Later commands reuse the daemon, so the prompt fires once for that tab and the connection is already there. Those daemons exit after twenty minutes without activity, which is a self-cleanup measure rather than a guarantee: while a daemon is alive it is a live handle on a logged-in tab, and nothing in the design invalidates it when the agent stops asking questions. The commands themselves define the ceiling on what that handle is worth, since the list includes evaluating expressions in page context and navigating a tab to a URL.

CDP_PORT_FILE decides where the tool reads its address from

The connection details come from a file the browser writes. Chrome records its debugging port in a file named DevToolsActivePort, and the skill reads it to learn where to connect. For a browser that keeps that file somewhere unusual, there is an escape hatch: set CDP_PORT_FILE to the full path, and the tool reads that instead. Auto-detection covers Chrome, Chromium, Brave, Edge and Vivaldi across macOS, Linux and Windows, so the override exists for the cases detection misses rather than for the mainstream ones. The mechanism is worth stating plainly because it inverts a trust assumption. A path in an environment variable is a path someone can write, and the tool will treat whatever it finds there as the address of the browser it is about to take control of. Anyone running this from a shared machine or an agent sandbox should decide who can write that path.

The 100 tab claim arrives without a measurement

The comparison section names its alternative and makes two claims. chrome-devtools-mcp, it says, reconnects on every command, so Chrome's Allow debugging prompt can reappear repeatedly and target enumeration times out when many tabs are open. Its own approach is offered as the opposite: one persistent daemon per tab, the modal once, and reliable handling of 100 or more tabs, where tools built on Puppeteer often time out during target enumeration. The mechanism explains the first claim, since holding a connection is exactly what avoids repeated reconnection. The second claim is asserted without anything behind it. No tab count, no enumeration timing, no machine, no comparison run appears in the file, so 100 or more is a statement of experience rather than a result, and it is worth treating as such when the alternative is a project that documents its own limitation in the same paragraph.

The command list stops mid-command and the screenshot path is unnamed

The usage block lists eight verbs and then stops in the middle of the eighth:

bash
scripts/cdp.mjs list                              # list open tabs
scripts/cdp.mjs shot   <target>                   # screenshot → runtime dir
scripts/cdp.mjs snap   <target>                   # accessibility tree (compact, semantic)
scripts/cdp.mjs html   <target> [".selector"]     # full HTML or scoped to CSS selector
scripts/cdp.mjs eval   <target> "expression"      # evaluate JS in page context
scripts/cdp.mjs nav    <target> https://...       # navigate and wait for load
scripts/cdp.mjs net    <target>                   # network resource timing
scripts/cdp.mjs click  <target> "s

Targets are addressed by a unique prefix of the target id that list prints, which means disambiguation is the caller's job whenever two ids share a prefix. Screenshots are described as going to a runtime directory, and no path for that directory is given anywhere in the file, so where captured images land is something you learn by running it rather than by reading it. Of the three ways to read a page, snap returns the accessibility tree and is the most economical about what it hands over; html and shot return the page itself.

Editorial conclusion

Use it on a browser profile that is not signed into anything you would mind an agent reading, and turn the remote debugging switch off again when you are done, because the tool is only as contained as that port is. Three things to settle first. The switch you toggle in Chrome is not scoped to this project: it opens remote debugging for the browser, so anything else on the machine that can reach that port inherits the same control over the same logged-in session. The commands include evaluating arbitrary JavaScript in a page and screenshotting it, so an agent using it can act as you in any site you are signed into, which is a larger grant than reading a page. And the install line in the project file pins an older tag than the current release, so installing from it does not give you the newest published version.

Frequently asked questions

How does chrome-cdp connect to Chrome?

It connects directly to Chrome's remote debugging WebSocket, with no Puppeteer and no intermediary. On first access to a tab it spawns a lightweight background daemon that holds the session open, so Chrome's Allow debugging prompt appears once per tab instead of on every command, and those daemons exit after 20 minutes of inactivity.

What does the chrome-cdp skill need installed?

Node.js 22 or newer, with no package install step. You either install it as a pi skill, or clone or copy the skills/chrome-cdp directory into wherever your agent loads skills from, which is the documented route for Amp, Claude Code and Cursor. Remote debugging also has to be enabled in the browser itself.

Which browsers can the chrome-cdp skill attach to?

Chrome, Chromium, Brave, Edge and Vivaldi, on macOS, Linux and Windows, through automatic detection. If the browser keeps its DevToolsActivePort file somewhere non-standard, the CDP_PORT_FILE environment variable points the tool at the full path to read instead.

What commands does the cdp.mjs command line provide?

Eight, addressed by a unique prefix of the target id printed by list: list for open tabs, shot for a screenshot, snap for a compact semantic accessibility tree, html for full markup or a CSS selector, eval to evaluate a JavaScript expression in page context, nav to navigate and wait for load, net for network resource timing, and click, whose line is cut off in the project's own usage block.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pasky-chrome-cdp-skill.svg)](https://hysenlabs.com/projects/pasky-chrome-cdp-skill)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pasky-chrome-cdp-skill.svg)](https://hysenlabs.com/projects/pasky-chrome-cdp-skill)

Was this useful?