---
name: chrome-cdp
description: Connect to user's local Chrome session. Inspect and interact with web pages in a headful browser shared with user cookies and login states — navigate pages, click buttons, take screenshots, test web apps in headful Chrome the user could see in real-time. Use for headful browser automation. This skill should be used when user says "use my browser", "open this page", "in my Chrome", "fill the form", "test in real browser", "show in browser", "my login account". Request explicit user approval before use.
---

# Chrome CDP

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

## Constraints

MUST explicitly ask for user permission before use. Chrome CDP runs in a **headful browser** in user screen. Start using Chrome CDP without user confirmation is **offensive**. User refuse: PAUSE IMMEDIATELY.

The headful browser will be the Chrome that user uses everyday with cookies and login states. Social media interactions requires user confirm.

Use `agent-browser` skill instead if you need stateless and headless access to web pages.

## Prerequisites

- Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open `chrome://inspect/#remote-debugging` and toggle the switch
- Node.js 22+ (uses built-in WebSocket)
- If your browser's `DevToolsActivePort` is in a non-standard location, set `CDP_PORT_FILE` to its full path

## 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.

### List open pages

```bash
scripts/cdp.mjs list
```

### Take a screenshot

```bash
scripts/cdp.mjs shot <target> [file]    # default: screenshot-<target>.png in runtime dir
```

Captures the **viewport only**. Scroll first with `eval` if you need content below the fold. Output includes the page's DPR and coordinate conversion hint (see **Coordinates** below).

### Accessibility tree snapshot

```bash
scripts/cdp.mjs snap <target>
```

### Evaluate JavaScript

```bash
scripts/cdp.mjs eval <target> <expr>
```

> **Watch out:** avoid index-based selection (`querySelectorAll(...)[i]`) across multiple `eval` calls when the DOM can change between them (e.g. after clicking Ignore, card indices shift). Collect all data in one `eval` or use stable selectors.

### Other commands

```bash
scripts/cdp.mjs html    <target> [selector]   # full page or element HTML
scripts/cdp.mjs nav     <target> <url>         # navigate and wait for load
scripts/cdp.mjs net     <target>               # resource timing entries
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 type    <target> <text>         # Input.insertText at current focus; works in cross-origin iframes unlike eval
scripts/cdp.mjs loadall <target> <selector> [ms]  # click "load more" until gone (default 1500ms between clicks)
scripts/cdp.mjs evalraw <target> <method> [json]  # raw CDP command passthrough
scripts/cdp.mjs open    [url]                  # open new tab (each triggers Allow prompt)
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

- Prefer `snap --compact` over `html` for page structure.
- Use `type` (not eval) to enter text in cross-origin iframes — `click`/`clickxy` to focus first, then `type`.
- Follow the startup error literally: the CLI distinguishes a network-disabled Codex sandbox, an unreachable DevTools port, a rejected WebSocket, and a pending Chrome "Allow debugging" prompt. Do not infer an Allow prompt from other failures.
- Chrome shows an "Allow debugging" modal **once per hub lifetime** (not per command, not per tab). A single background hub holds one WebSocket to Chrome; every command — `list`, `open`, and per-tab ops — routes through it. The hub auto-exits after 8 hours of inactivity or when Chrome disconnects. `stop <target>` detaches one tab's session; `stop` with no args ends the hub.