chrome-cdp

name	chrome-cdp
description	Interact with local Chrome browser session (only on explicit user approval after being asked to inspect, debug, or interact with a page open in Chrome)

Chrome CDP

Lightweight Chrome DevTools Protocol CLI. Connects directly via WebSocket — no Puppeteer, works with 100+ tabs, instant connection.

Prerequisites

• Chrome with remote debugging enabled: open chrome://inspect/#remote-debugging and toggle the switch
• Node.js 22+ (uses built-in WebSocket)

Commands

All commands use scripts/cdp.mjs. The <target> is a unique targetId prefix from list; copy the full prefix shown in the list output (for example 6BE827FA). The CLI rejects ambiguous prefixes.

Page discovery

scripts/cdp.mjs list                           # list open pages
scripts/cdp.mjs info    <target>               # page state: URL, title, viewport, scroll, focus, forms, iframes

Run info first to orient yourself on any page.

Reading

scripts/cdp.mjs snap    <target> [selector]    # accessibility tree (full page or scoped to selector)
scripts/cdp.mjs text    <target> [selector]    # text content (innerText, not HTML) — much cheaper than html
scripts/cdp.mjs html    <target> [selector]    # full page or element HTML
scripts/cdp.mjs eval    <target> <expr>        # evaluate JS expression
scripts/cdp.mjs shot    <target> [file]        # screenshot (default: /tmp/screenshot.png)
scripts/cdp.mjs net     <target>               # resource timing entries
scripts/cdp.mjs console <target> [count]       # last N console messages (default 20) — useful for debugging JS errors

Watch out: avoid index-based selection (querySelectorAll(...)[i]) across multiple eval calls when the DOM can change between them. Collect all data in one eval or use stable selectors.

Navigation

scripts/cdp.mjs nav     <target> <url>         # navigate to URL and wait for load
scripts/cdp.mjs back    <target>               # browser back and wait for load
scripts/cdp.mjs forward <target>               # browser forward and wait for load
scripts/cdp.mjs reload  <target>               # reload page and wait for load
scripts/cdp.mjs scroll  <target> [direction]   # scroll: down (default), up, top, bottom

Interaction

scripts/cdp.mjs click   <target> <selector>       # click element by CSS selector
scripts/cdp.mjs clickxy <target> <x> <y>           # click at CSS pixel coords
scripts/cdp.mjs hover   <target> <selector>        # hover element (triggers :hover CSS and mouse events)
scripts/cdp.mjs focus   <target> <selector>        # focus element (no click side effects)
scripts/cdp.mjs clear   <target> <selector>        # clear input/textarea/contenteditable (React-compatible)
scripts/cdp.mjs type    <target> <text>             # type text at current focus (works in cross-origin iframes)
scripts/cdp.mjs key     <target> <key>              # key press: Enter, Tab, Escape, Backspace, ArrowDown, etc.
scripts/cdp.mjs select  <target> <selector> <value> # pick <select> option by value or visible text

Waiting

scripts/cdp.mjs wait     <target> <selector> [ms]  # wait for element to appear (default 10s)
scripts/cdp.mjs waitgone <target> <selector> [ms]  # wait for element to disappear (default 10s)
scripts/cdp.mjs loadall  <target> <selector> [ms]  # click "load more" until gone (1500ms interval, 5min cap)

Advanced

scripts/cdp.mjs evalraw <target> <method> [json]   # raw CDP command passthrough
scripts/cdp.mjs stop    [target]                    # stop daemon(s)

Coordinates

shot saves an image at native resolution: image pixels = CSS pixels × DPR. CDP Input events (clickxy etc.) take CSS pixels.

CSS px = screenshot image px / DPR

shot prints the DPR for the current page. Typical Retina (DPR=2): divide screenshot coords by 2.

Tips

• Run info after every action to confirm state changes.
• Prefer snap over html for page structure. Use snap <target> <selector> to scope to a subtree and save tokens on large pages.
• Use text instead of html when you only need the content — much cheaper in tokens.
• Form filling pattern: focus → clear → type → key Tab (or key Enter to submit). The clear command uses native property setters so it works with React/framework-controlled inputs.
• select matches by value first, then by visible text. On failure it lists all available options so you can self-correct.
• Use hover for dropdown menus and tooltip reveals.
• Use waitgone after actions that trigger loading spinners or toast notifications.
• Use console to check for JS errors when something isn't working.
• Use type (not eval) to enter text in cross-origin iframes — focus first, then type.
• Chrome shows an "Allow debugging" modal once per tab on first access. A background daemon keeps the session alive so subsequent commands need no further approval. Daemons auto-exit after 20 minutes of inactivity.