chrome-cdp: Live Chrome Session for AI Agents
Skill by ara.so — Daily 2026 Skills collection.
chrome-cdp connects your AI agent directly to your running Chrome browser via the Chrome DevTools Protocol (CDP). Unlike browser automation tools that spin up fresh isolated browsers, this connects to tabs you already have open — with your logins, cookies, and current page state intact.
What It Does
- Live session access — reads and interacts with tabs you're already logged into
- Persistent daemon — one WebSocket daemon per tab; the "Allow debugging" modal appears once, not on every command
- No npm install — only Node.js 22+ required
- 100+ tab support — handles large numbers of open tabs reliably
- Cross-origin iframe support —
type command works even inside cross-origin iframes
Installation
As a pi skill
pi install git:github.com/pasky/[email protected]
Manual (for Amp, Claude Code, Cursor, Codex, etc.)
git clone https://github.com/pasky/chrome-cdp-skill
Enable Remote Debugging in Chrome
- Open Chrome and navigate to:
chrome://inspect/#remote-debugging
- Toggle the "Enable remote debugging" switch
That's all. No flags, no relaunching Chrome.
The script auto-detects Chrome, Chromium, Brave, Edge, and Vivaldi on macOS, Linux, and Windows. For non-standard installs:
export CDP_PORT_FILE=/path/to/DevToolsActivePort
Key Commands
All commands use scripts/cdp.mjs as the entry point. <target> is a unique prefix of the targetId shown by list.
List Open Tabs
node scripts/cdp.mjs list
Screenshot a Tab
node scripts/cdp.mjs shot A1B2
Accessibility Tree (Semantic Snapshot)
node scripts/cdp.mjs snap A1B2
Full HTML or Scoped HTML
node scripts/cdp.mjs html A1B2
node scripts/cdp.mjs html A1B2 ".main-content"
node scripts/cdp.mjs html A1B2 "#article-body"
Evaluate JavaScript
node scripts/cdp.mjs eval A1B2 "document.title"
node scripts/cdp.mjs eval A1B2 "window.location.href"
node scripts/cdp.mjs eval A1B2 "document.querySelectorAll('a').length"
Navigate to URL
node scripts/cdp.mjs nav A1B2 https://example.com
Network Resource Timing
node scripts/cdp.mjs net A1B2
Click an Element
node scripts/cdp.mjs click A1B2 "button.submit"
node scripts/cdp.mjs click A1B2 "#login-btn"
node scripts/cdp.mjs click A1B2 "[data-testid='confirm']"
Click at Coordinates
node scripts/cdp.mjs clickxy A1B2 320 480
Type Text
node scripts/cdp.mjs type A1B2 "Hello, world!"
Load More (Click Until Gone)
node scripts/cdp.mjs loadall A1B2 "button.load-more"
Open a New Tab
node scripts/cdp.mjs open
node scripts/cdp.mjs open https://example.com
Stop Daemons
node scripts/cdp.mjs stop
node scripts/cdp.mjs stop A1B2
Raw CDP Command Passthrough
node scripts/cdp.mjs evalraw A1B2 "Page.getFrameTree"
node scripts/cdp.mjs evalraw A1B2 "Runtime.evaluate" '{"expression":"1+1"}'
Common Patterns
Pattern: Read a Page You're Logged Into
node scripts/cdp.mjs list
node scripts/cdp.mjs snap D4E5
node scripts/cdp.mjs html D4E5 ".email-list"
Pattern: Fill and Submit a Form
node scripts/cdp.mjs click A1B2 "input[name='search']"
node scripts/cdp.mjs type A1B2 "my search query"
node scripts/cdp.mjs click A1B2 "button[type='submit']"
node scripts/cdp.mjs shot A1B2
Pattern: Extract Data with JavaScript
node scripts/cdp.mjs eval A1B2 "Array.from(document.querySelectorAll('a')).map(a => a.href)"
node scripts/cdp.mjs eval A1B2 "document.querySelector('.price').textContent.trim()"
node scripts/cdp.mjs eval A1B2 "
Array.from(document.querySelectorAll('table tr')).map(row =>
Array.from(row.querySelectorAll('td,th')).map(cell => cell.textContent.trim())
)
"
Pattern: Navigate and Wait
node scripts/cdp.mjs nav A1B2 https://news.ycombinator.com
node scripts/cdp.mjs snap A1B2
Pattern: Paginated Content
node scripts/cdp.mjs loadall A1B2 "button[data-action='load-more']"
node scripts/cdp.mjs eval A1B2 "document.querySelectorAll('.item').length"
Pattern: Script Integration (Node.js)
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const exec = promisify(execFile);
const CDP = (...args) => exec('node', ['scripts/cdp.mjs', ...args]);
async function getPageTitle(tabPrefix) {
const { stdout } = await CDP('eval', tabPrefix, 'document.title');
return stdout.trim();
}
async function takeScreenshot(tabPrefix) {
const { stdout } = await CDP('shot', tabPrefix);
return stdout.trim();
}
async function navigateAndSnap(tabPrefix, url) {
await CDP('nav', tabPrefix, url);
const { stdout } = await CDP('snap', tabPrefix);
return stdout;
}
const tabs = (await CDP('list')).stdout;
console.log(tabs);
Configuration
| Environment Variable |
Purpose |
CDP_PORT_FILE |
Path to DevToolsActivePort file for non-standard browser installs |
Daemons auto-exit after 20 minutes of inactivity — no manual cleanup needed in normal use.
Troubleshooting
"Allow debugging" modal keeps appearing
This happens if daemons aren't persisting. Make sure you're using the same scripts/cdp.mjs entry point — it manages daemon lifecycle automatically. If you switched tools mid-session, run stop and let daemons restart fresh.
Browser not detected
If auto-detection fails, find your DevToolsActivePort file and set the env var:
export CDP_PORT_FILE="$HOME/Library/Application Support/Google/Chrome/Default/DevToolsActivePort"
export CDP_PORT_FILE="$HOME/.config/google-chrome/Default/DevToolsActivePort"
Target not found / prefix ambiguous
Run list again — tab IDs change when tabs are closed/reopened. Use a longer prefix if multiple tabs share the same prefix characters.
Remote debugging toggle not visible
Ensure you're on chrome://inspect/#remote-debugging (not just chrome://inspect/). The toggle is in the top-right of the page.
Node.js version error
This project requires Node.js 22+. Check with node --version and upgrade if needed via nvm or your package manager.
Screenshots are blank or wrong size
The screenshot reflects the actual rendered viewport. If the tab is in a background window or the OS has display scaling, pixel coordinates for clickxy may need adjustment. Use snap or eval to inspect DOM state instead of relying solely on screenshots.
