| name | chrome-cdp |
| description | Interacts with local browser via Chrome DevTools Protocol (only triggered after user explicitly requests to inspect, debug, or interact with pages open in Chrome) |
Chrome CDP
Lightweight Chrome DevTools Protocol CLI. Direct connection via WebSocket, no Puppeteer required, supports 100+ tabs, instant connection.
Prerequisites
- Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open
chrome://inspect/#remote-debugging and turn on the switch
- Node.js 22+ (uses built-in WebSocket)
- If the browser's
DevToolsActivePort is in a non-standard location, set CDP_PORT_FILE to its full path
Commands
All commands use scripts/cdp.mjs. <target> is the unique targetId prefix from list output; copy the full prefix shown (e.g., 6BE827FA). CLI rejects ambiguous prefixes.
List Open Pages
scripts/cdp.mjs list
Screenshot
scripts/cdp.mjs shot <target> [file]
Only captures the viewport. If content outside the viewport is needed, use eval to scroll first. Output includes page DPR and coordinate transformation hints (see Coordinates section below).
Accessibility Tree Snapshot
scripts/cdp.mjs snap <target>
Execute JavaScript
scripts/cdp.mjs eval <target> <expr>
Note: Avoid using index-based selections (querySelectorAll(...)[i]) across multiple eval calls, as DOM may change between calls (e.g., after ignoring clicks, indices shift). Collect all data in one eval or use stable selectors.
Other Commands
scripts/cdp.mjs html <target> [selector]
scripts/cdp.mjs nav <target> <url>
scripts/cdp.mjs net <target>
scripts/cdp.mjs click <target> <selector>
scripts/cdp.mjs clickxy <target> <x> <y>
scripts/cdp.mjs type <target> <text>
scripts/cdp.mjs loadall <target> <selector> [ms]
scripts/cdp.mjs evalraw <target> <method> [json]
scripts/cdp.mjs open [url]
scripts/cdp.mjs stop [target>
Coordinates
shot saves images at native resolution: image pixels = CSS pixels × DPR. CDP Input events (clickxy etc.) use CSS pixels.
CSS px = Screenshot pixels / DPR
shot prints DPR for the current page. Typical Retina (DPR=2): divide screenshot coordinates by 2.
Tips
- Prefer
snap --compact over html for viewing page structure.
- For typing text in cross-origin iframes, use
type (not eval) — first focus with click/clickxy, then type.
- Chrome shows "Allow debugging" modal on first access to each tab. Background daemon keeps session alive, subsequent commands don't need re-approval. Daemon auto-exits after 20 minutes of inactivity.