https://github.com/pasky/chrome-cdp-skill
Give your AI agent access to your live Chrome session — works out of the box, connects to tabs you already have open
https://github.com/pasky/chrome-cdp-skill
Last synced: 8 days ago
JSON representation
Give your AI agent access to your live Chrome session — works out of the box, connects to tabs you already have open
- Host: GitHub
- URL: https://github.com/pasky/chrome-cdp-skill
- Owner: pasky
- Created: 2026-03-13T00:35:39.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-13T23:22:35.000Z (about 1 month ago)
- Last Synced: 2026-03-14T02:22:09.023Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 18.6 KB
- Stars: 192
- Watchers: 0
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-claude-code - **chrome-cdp-skill**
README
# chrome-cdp
Let your AI agent see and interact with your **live Chrome session** — the tabs you already have open, your logged-in accounts, your current page state. No browser automation framework, no separate browser instance, no re-login.
Works out of the box with any Chrome installation. One toggle to enable, nothing else to install.
## Why this matters
Most browser automation tools launch a fresh, isolated browser. This one connects to the Chrome you're already running, so your agent can:
- Read pages you're logged into (Gmail, GitHub, internal tools, ...)
- Interact with tabs you're actively working in
- See the actual state of a page mid-workflow, not a clean reload
## Installation
### As a pi skill
```bash
pi install git:github.com/pasky/chrome-cdp-skill@v1.0.1
```
### For other agents (Amp, Claude Code, Cursor, etc.)
Clone or copy the `skills/chrome-cdp/` directory wherever your agent loads skills or context from. The only runtime dependency is **Node.js 22+** — no npm install needed.
### Enable remote debugging in Chrome
Navigate to `chrome://inspect/#remote-debugging` and toggle the switch. That's it.
The CLI auto-detects Chrome, Chromium, Brave, Edge, and Vivaldi on macOS, Linux, and Windows. If your browser stores `DevToolsActivePort` in a non-standard location, set the `CDP_PORT_FILE` environment variable to the full path.
## Usage
```bash
scripts/cdp.mjs list # list open tabs
scripts/cdp.mjs shot # screenshot → runtime dir
scripts/cdp.mjs snap # accessibility tree (compact, semantic)
scripts/cdp.mjs html [".selector"] # full HTML or scoped to CSS selector
scripts/cdp.mjs eval "expression" # evaluate JS in page context
scripts/cdp.mjs nav https://... # navigate and wait for load
scripts/cdp.mjs net # network resource timing
scripts/cdp.mjs click "selector" # click element by CSS selector
scripts/cdp.mjs clickxy # click at CSS pixel coordinates
scripts/cdp.mjs type "text" # type at focused element (works in cross-origin iframes)
scripts/cdp.mjs loadall "selector" # click "load more" until gone
scripts/cdp.mjs evalraw [json] # raw CDP command passthrough
scripts/cdp.mjs open [url] # open new tab (triggers Allow prompt)
scripts/cdp.mjs stop [target] # stop daemon(s)
```
`` is a unique prefix of the targetId shown by `list`.
## Why not chrome-devtools-mcp?
[chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) reconnects on every command, so Chrome's "Allow debugging" modal can re-appear repeatedly and target enumeration times out with many tabs open. `chrome-cdp` holds one persistent daemon per tab — the modal fires once, and it handles 100+ tabs reliably.
## How it works
Connects directly to Chrome's remote debugging WebSocket — no Puppeteer, no intermediary. On first access to a tab, a lightweight background daemon is spawned that holds the session open. Chrome's "Allow debugging" modal appears once per tab; subsequent commands reuse the daemon silently. Daemons auto-exit after 20 minutes of inactivity.
This approach is also why it handles 100+ open tabs reliably, where tools built on Puppeteer often time out during target enumeration.