### Take Screenshot Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to take a screenshot of a specific target and save it to a file.

```bash
node scripts/cdp.mjs shot 6BE8 /tmp/screenshot.png
# /tmp/screenshot.png
# Screenshot saved. Device pixel ratio (DPR): 2
# ...
```

--------------------------------

### Accessibility Tree Snapshot Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to take an accessibility tree snapshot of a specific target.

```bash
node scripts/cdp.mjs snap 6BE8
# [document] Google Search
#   [navigation] ...
```

--------------------------------

### List Open Pages Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to list all open Chrome tabs, showing target IDs and URLs.

```bash
node scripts/cdp.mjs list
# 6BE827FA  Google Chrome                                      https://www.google.com
```

--------------------------------

### Load All Command Use Case Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

This example demonstrates the 'loadall' command used with a different CSS selector and interval, showing a typical interaction for loading paginated content.

```json
{"id": 1, "cmd": "loadall", "args": [".pagination-next", "1500"]}
→ {"id": 1, "ok": true, "result": "Clicked \".pagination-next\" 47 time(s) until it disappeared"}
```

--------------------------------

### Click Element Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to click an element identified by a CSS selector within a specific target.

```bash
node scripts/cdp.mjs click 6BE8 'button.search'
# Clicked <BUTTON> "Search"
```

--------------------------------

### Example Network Resource Output

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

This example demonstrates the expected format for network resource output, including right-aligned columns for duration, transfer size, resource type, and URL. Note the '?' for unavailable transfer sizes.

```text
    0ms     3247B  script    https://example.com/app.js
   152ms    45612B  fetch     https://api.example.com/data.json
   203ms   234456B  image     https://cdn.example.com/logo.png
   305ms        ?B  script    https://analytics.google.com/ga.js
```

--------------------------------

### Install Chrome CDP Skill

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Install the skill as a pi skill or copy it to another agent's skills directory.

```bash
# As a pi skill
pi install git:github.com/pasky/chrome-cdp-skill@v1.0.1

# For other agents
# Copy skills/chrome-cdp/ to your agent's skills directory
```

--------------------------------

### Stop Daemon Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to stop the daemon process associated with a specific target.

```bash
node scripts/cdp.mjs stop 6BE8
# (stops the daemon for that target)
```

--------------------------------

### Evaluate JavaScript Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Example of using the CLI to evaluate a JavaScript expression within a specific target's context.

```bash
node scripts/cdp.mjs eval 6BE8 'document.title'
# Google
```

--------------------------------

### Unix Socket Path Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Example of a Unix domain socket path used for daemon communication. Sockets are created in the runtime directory with specific permissions.

```bash
~/.cache/cdp/cdp-6BE827FA5B2C1E3D.sock
```

--------------------------------

### Get or Start Tab Daemon

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Connects to an existing Chrome CDP daemon or starts a new one if necessary. It includes retry logic for connection attempts.

```javascript
async function getOrStartTabDaemon(targetId: string): Promise<net.Socket>
```

--------------------------------

### Install chrome-cdp Skill

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/README.md

Install the chrome-cdp skill using the pi package manager. Ensure you are using version v1.0.1 or later.

```bash
pi install git:github.com/pasky/chrome-cdp-skill@v1.0.1
```

--------------------------------

### Cache File Format Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Example of the JSON array format used for the pages.json cache file, storing discovered target information.

```json
[
  {
    "targetId": "6BE827FA5B2C1E3D",
    "title": "Google Chrome",
    "url": "https://www.google.com",
    "type": "page"
  },
  {
    "targetId": "4A9F2E1C8B7D6A5B",
    "title": "Stack Overflow",
    "url": "https://stackoverflow.com/questions/newest",
    "type": "page"
  }
]
```

--------------------------------

### Example Workflow for Typing Text

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Demonstrates a typical workflow for typing text, which involves first clicking to focus an input element and then using the 'type' command.

```json
{"id": 1, "cmd": "click", "args": ["input#search"]}
→ {"id": 1, "ok": true, "result": "Clicked <INPUT> ..."}

{"id": 2, "cmd": "type", "args": ["search query"]}
→ {"id": 2, "ok": true, "result": "Typed 12 characters"}
```

--------------------------------

### Windows Named Pipe Path Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Example of a Windows named pipe path used to simulate Unix domain sockets for daemon communication.

```powershell
"\\.\pipe\cdp-6BE827FA5B2C1E3D"
```

--------------------------------

### Screenshot Output Format Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

This illustrates the typical output format for a screenshot, including the file path, save confirmation, and coordinate mapping instructions based on the device pixel ratio.

```text
/path/to/screenshot.png
Screenshot saved. Device pixel ratio (DPR): 2
Coordinate mapping:
  Screenshot pixels → CSS pixels (for CDP Input events): divide by 2
  e.g. screenshot point (100, 200) → CSS (50, 100) → use clickxy <target> 50 100
  On this 2x display: CSS px = screenshot px / 2 ≈ screenshot px × 0.5
```

--------------------------------

### Browser Interaction Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Examples of commands for interacting with the browser, such as clicking elements, typing text, and navigating pages. These are part of the core API reference.

```bash
cdp-skill browser click "#myButton"
cdp-skill browser type "#myInput" "Hello World"
cdp-skill browser navigate "https://example.com"
```

--------------------------------

### Basic command testing

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Provides examples of basic commands for testing the CDP skill's functionality, including listing targets, taking snapshots, and evaluating simple expressions.

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

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

```bash
node scripts/cdp.mjs eval <target> '2+2'
```

--------------------------------

### Docker Deployment of cdp.mjs

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Dockerfile to set up a container with Node.js, Chrome, and the cdp.mjs script. Starts by listing available targets.

```dockerfile
FROM node:22

RUN apt-get update && apt-get install -y chromium-browser

COPY scripts/cdp.mjs /opt/cdp.mjs

CMD ["node", "/opt/cdp.mjs", "list"]
```

--------------------------------

### Handle Missing Selector in Load All Command

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when the `loadall` command is called without a required CSS selector.

```text
Error: CSS selector required
```

--------------------------------

### Catch Daemon Start Error

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

This command helps detect if the daemon process failed to start, often due to a missing user confirmation in Chrome. The error message indicates a failure to reach the daemon socket.

```bash
node scripts/cdp.mjs eval 6BE8 'document.title' 2>&1 | grep -q "did you click Allow"
```

--------------------------------

### Get network resource timing entries

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Retrieves network resource timing entries for the specified target.

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

--------------------------------

### Get HTML of a page or element

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Fetches the full HTML of the page or the HTML of a specific element identified by a CSS selector.

```bash
scripts/cdp.mjs html    <target> [selector]
```

--------------------------------

### Get the accessibility tree snapshot

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Retrieves a snapshot of the accessibility tree for the specified target.

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

--------------------------------

### Error: Daemon failed to start

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

This error signifies that the daemon socket could not be reached after multiple retries. Ensure you have clicked 'Allow' on the debugging prompt in Chrome.

```text
Error: Daemon failed to start — did you click Allow in Chrome?
```

--------------------------------

### Example Error Output

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Demonstrates the typical error output when a command fails, such as an evaluation error. The script exits with code 1 on failure.

```bash
$ node scripts/cdp.mjs eval 6BE8 'nonexistent.property'
Error: nonexistent is not defined
```

--------------------------------

### Handle Navigation Timeout Errors

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when a navigation operation exceeds the configured timeout limit.

```text
Error: Timed out waiting for navigation to finish (last readyState: loading)
```

--------------------------------

### Handle Missing Text in Type Command

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when the `type` command is invoked without providing any text to input.

```text
Error: text required
```

--------------------------------

### NDJSON Protocol Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Illustrates the newline-delimited JSON format used for daemon Inter-Process Communication (IPC).

```json
{"id": 1, "cmd": "snap", "args": []}
{"id": 1, "ok": true, "result": "[document] ..."}

```

--------------------------------

### Handle Invalid URL Errors in Navigation

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when the provided URL to the navigation command has an invalid format.

```text
Error: Invalid URL: not a url
```

--------------------------------

### CLI Error Example

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Demonstrates how errors thrown during CDP command execution are reported to stderr with an exit code of 1.

```bash
$ node scripts/cdp.mjs eval 6BE8 'throw new Error("oops")'
Error: oops
```

--------------------------------

### Handle Target Resolution Errors

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

These JavaScript examples demonstrate how to catch errors when resolving target IDs using a prefix. The first catches cases where no target matches the prefix, and the second handles ambiguous prefixes.

```javascript
try {
  resolvePrefix('ZZZZ', targetIds);
} catch (e) {
  console.error('Target not found:', e.message);
}
```

```javascript
try {
  resolvePrefix('6BE8', targetIds); // multiple targets start with 6BE8
} catch (e) {
  console.error('Ambiguous target:', e.message);
}
```

--------------------------------

### Enable Remote Debugging in Chrome

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/README.md

To enable remote debugging, navigate to chrome://inspect/#remote-debugging in your Chrome browser and toggle the switch. This is a one-time setup per Chrome installation.

```bash
chrome://inspect/#remote-Debugging
```

--------------------------------

### Get Network Resource Timing Entries

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Use this command to retrieve a list of network resource timing entries. The response provides a plain-text table of resources, including their transfer size, type, and URL.

```json
{"id": 1, "cmd": "net", "args": []}
```

```json
{"id": 1, "ok": true, "result": "    0ms     3247B  script    https://example.com/script.js\n   152ms    45612B  script    https://cdn.example.com/framework.js"}
```

--------------------------------

### IPC Protocol Example Response

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

An example of a response message formatted according to the newline-delimited JSON (NDJSON) protocol.

```json
{"id":1,"ok":true,"result":"[document] ..."}\n
```

--------------------------------

### Create RUNTIME_DIR with Permissions

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Creates the runtime directory with recursive option and sets permissions to 0o700 (owner rwx only). Handles potential errors during creation.

```javascript
try { mkdirSync(RUNTIME_DIR, { recursive: true, mode: 0o700 }); } catch {}
```

--------------------------------

### IPC Protocol Example Request

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

An example of a request message formatted according to the newline-delimited JSON (NDJSON) protocol.

```json
{"id":1,"cmd":"snap","args":[]}\n
```

--------------------------------

### Use a Custom Chrome Instance

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Configure the skill to connect to a custom or remote Chrome instance by setting environment variables for the host and the port file.

```bash
export CDP_HOST=192.168.1.100  # Remote Chrome
export CDP_PORT_FILE=/path/to/DevToolsActivePort
node scripts/cdp.mjs list
```

--------------------------------

### main() CLI Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Parses command-line arguments and dispatches to the appropriate handler. This is the main entry point for the CDP CLI tool.

```APIDOC
## main()

### Description
Parses command-line arguments and dispatches to the appropriate handler.

### Supported Commands

| Command | Arguments | Description |
|---|---|---|
| `list` or `ls` | — | List all open pages |
| `snap` or `snapshot` | `<target>` | Accessibility tree snapshot |
| `eval` | `<target> <expression>` | Evaluate JavaScript |
| `shot` or `screenshot` | `<target> [file]` | Take a screenshot |
| `html` | `<target> [selector]` | Get HTML |
| `nav` or `navigate` | `<target> <url>` | Navigate to URL |
| `net` or `network` | `<target>` | Network timing |
| `click` | `<target> <selector>` | Click element by selector |
| `clickxy` | `<target> <x> <y>` | Click at coordinates |
| `type` | `<target> <text>` | Type text (spaces allowed) |
| `loadall` | `<target> <selector> [ms]` | Load more until gone |
| `evalraw` | `<target> <method> [json]` | Raw CDP command |
| `open` | `[url]` | Open new tab |
| `stop` | `[target]` | Stop daemon(s) |
| `help`, `--help`, `-h` | — | Show usage |

### Example Usage
```bash
node scripts/cdp.mjs list
# 6BE827FA  Google Chrome                                      https://www.google.com

node scripts/cdp.mjs snap 6BE8
# [document] Google Search
#   [navigation] ...

node scripts/cdp.mjs eval 6BE8 'document.title'
# Google

node scripts/cdp.mjs click 6BE8 'button.search'
# Clicked <BUTTON> "Search"

node scripts/cdp.mjs shot 6BE8 /tmp/screenshot.png
# /tmp/screenshot.png
# Screenshot saved. Device pixel ratio (DPR): 2
# ...

node scripts/cdp.mjs stop 6BE8
# (stops the daemon for that target)
```
```

--------------------------------

### CDP Class Constructor

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Demonstrates how to instantiate the main CDP class for low-level WebSocket client interaction.

```javascript
const cdp = new CDP();

```

--------------------------------

### Navigate to a URL

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Navigates the specified target to a new URL and waits for the page to load.

```bash
scripts/cdp.mjs nav     <target> <url>
```

--------------------------------

### Navigate Target to URL

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Instruct a specified Chrome tab to navigate to a given URL. Replace <target> with a unique substring of the targetId and 'https://example.com' with the desired URL.

```bash
node scripts/cdp.mjs nav <target> 'https://example.com'
```

--------------------------------

### Instantiate CDP Client

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Creates a new CDP instance. Call connect() to establish a WebSocket connection before sending commands.

```javascript
new CDP()
```

--------------------------------

### Handle Non-Numeric Coordinates in Clickxy

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when `clickxy` receives coordinates that are not valid numbers.

```text
Error: x and y must be numbers (CSS pixels)
```

--------------------------------

### CDP Implementation Functions for Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Lists specific implementation functions for each CLI command, demonstrating how to interact with the CDP client for various operations.

```javascript
// Fetch all open pages
getPages(cdp)

// Format for display
formatPageList(pages)

// Accessibility tree
snapshotStr(cdp, sid, compact?)

// Evaluate JavaScript
evalStr(cdp, sid, expr)

// Screenshot
shotStr(cdp, sid, file?, targetId?)

// Get HTML
htmlStr(cdp, sid, selector?)

// Navigate
navStr(cdp, sid, url)

// Network timing
netStr(cdp, sid)

// Click element
clickStr(cdp, sid, selector)

// Click coordinates
clickXyStr(cdp, sid, x, y)

// Type text
typeStr(cdp, sid, text)

// Load more (pagination)
loadAllStr(cdp, sid, selector, ms?)

// Raw CDP command
evalRawStr(cdp, sid, method, json?)

// CLI entry point and dispatcher
main()

```

--------------------------------

### Get HTML

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Retrieves the full page HTML or the HTML of a specific element identified by a CSS selector.

```APIDOC
## Get HTML

### Description
Retrieve the full page HTML or a scoped element's HTML.

### Method
POST

### Endpoint
/html

### Parameters
#### Request Body
- **id** (number) - Required - Unique identifier for the request.
- **cmd** (string) - Required - Command name, should be "html".
- **args** (array) - Optional - An array of arguments. The first element can be a CSS selector string. If omitted, returns the full page HTML.

### Request Example
```json
{
  "id": 1,
  "cmd": "html",
  "args": ["button.primary"]
}
```

### Response
#### Success Response (200 OK)
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - true if command succeeded.
- **result** (string) - HTML string (outerHTML of the matched element, or full page if no selector).

#### Response Example
```json
{
  "id": 1,
  "ok": true,
  "result": "<button class=\"primary\">Click me</button>"
}
```

#### Error Response
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - false if command failed.
- **error** (string) - Error message.
```

--------------------------------

### Error: No target matching prefix

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

The provided prefix does not match any known target IDs. Run `cdp list` to view available targets and verify the prefix.

```text
Error: No target matching prefix "ZZZZ". Run "cdp list".
```

--------------------------------

### Wait for Page to Load

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Navigate to a URL and wait for the page load event and for the document's ready state to be 'complete'.

```bash
node scripts/cdp.mjs nav 6BE8 'https://example.com'
# Waits for Page.loadEventFired and document.readyState === 'complete'
```

--------------------------------

### Handle Non-HTTP/HTTPS URL Errors in Navigation

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when a URL uses a protocol other than http or https.

```text
Error: Only http/https URLs allowed, got: ftp://example.com
```

--------------------------------

### Command Implementations

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Reference for the CLI command implementations, such as 'snap', 'eval', 'shot', 'click', and 'type'.

```APIDOC
## Command Implementations

### Description
Functions that implement the CLI commands for various tasks.

### Commands
- `snap(target: string, options?: object)`: Takes a snapshot of a target.
- `eval(target: string, expression: string, options?: object)`: Evaluates JavaScript in a target.
- `shot(target: string, options?: object)`: Takes a screenshot of a target.
- `click(target: string, selector: string, options?: object)`: Clicks an element identified by a selector.
- `type(target: string, text: string, options?: object)`: Types text into an element.
```

--------------------------------

### Handle Invalid JSON Parameters for Evalraw

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when `evalraw` receives parameters that are not valid JSON.

```text
Error: Invalid JSON params: {not json}
```

--------------------------------

### Get Accessibility Tree

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Retrieve the accessibility tree for a specified target. Replace <target> with a unique substring of the targetId.

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

--------------------------------

### Basic CDP Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Commands for listing tabs, capturing the accessibility tree, and evaluating JavaScript expressions.

```bash
cdp list
cdp snap 6BE8
cdp eval 6BE8 'expression'
```

--------------------------------

### Evaluate JavaScript Expression Errors

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example of a JavaScript expression that would throw an error due to accessing a non-existent property.

```text
Error: document.nonexistent.property
```

--------------------------------

### Error: No page list cached

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

This error indicates that no command has been run to cache the list of available pages or targets. Execute `cdp list` to populate the cache.

```text
Error: No page list cached. Run "cdp list" first.
```

--------------------------------

### CLI Command Format

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Shows the general format for invoking the command-line interface of the chrome-cdp-skill.

```text
node scripts/cdp.mjs <command> [args]

```

--------------------------------

### CDP Constructor

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Creates a new CDP instance. The connection must be established separately using the `connect()` method.

```APIDOC
## Constructor

```javascript
new CDP()
```

Creates a new CDP instance with no active connection. Call `connect()` before sending commands.
```

--------------------------------

### Get accessibility tree

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Retrieves the accessibility tree (semantic view) of a target. This is useful for understanding the structure and accessibility of a web page.

```bash
node scripts/cdp.mjs snap 6BE8
```

--------------------------------

### Handle Element Not Found Errors in Click

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message when the CSS selector provided to the click command does not match any element on the page.

```text
Error: Element not found: .nonexistent
```

--------------------------------

### Project Directory Structure

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Illustrates the file and directory layout of the chrome-cdp-skill project.

```text
chrome-cdp-skill/
├── README.md                         # Installation, usage, why it's different
├── package.json                      # Node package metadata
├── LICENSE                           # MIT
└── skills/
    └── chrome-cdp/
        ├── SKILL.md                  # Skill definition for pi/Claude Code
        └── scripts/
            └── cdp.mjs               # Main CLI script (node 22+, no dependencies)

```

--------------------------------

### connect(wsUrl)

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Establishes a WebSocket connection to Chrome's remote debugging endpoint. Requires the WebSocket URL.

```APIDOC
## connect(wsUrl)

```javascript
async connect(wsUrl: string): Promise<void>
```

Establishes a WebSocket connection to Chrome's remote debugging endpoint.

### Parameters
#### Path Parameters
- **wsUrl** (string) - Required - WebSocket URL from `DevToolsActivePort` file, e.g. `ws://127.0.0.1:9222/devtools/browser/abc123...`

### Throws
- `Error` with message `"WebSocket error: ..."` if connection fails

### Example
```javascript
const cdp = new CDP();
const wsUrl = getWsUrl(); // parses DevToolsActivePort file
await cdp.connect(wsUrl);
```
```

--------------------------------

### Get Network Performance

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Retrieves network resource timing entries, providing details on duration, transfer size, resource type, and URL.

```APIDOC
## GET Network Performance

### Description
Get resource timing entries.

### Method
GET

### Endpoint
/network/performance

### Request Body
```json
{
  "id": 1,
  "cmd": "net",
  "args": []
}
```

### Response
#### Success Response (200 OK)
- **id** (number) - Echoes the request ID
- **ok** (boolean) - true if command succeeded
- **result** (string) - Plain-text table of resources (one per line)

#### Response Example
```json
{
  "id": 1,
  "ok": true,
  "result": "    0ms     3247B  script    https://example.com/script.js\n   152ms    45612B  script    https://cdn.example.com/framework.js"
}
```

#### Error Response
- **id** (number) - Echoes the request ID
- **ok** (boolean) - false if command failed
- **error** (string) - Error message
```

--------------------------------

### Target ID Prefix Matching

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Demonstrates how to use a unique substring of a targetId for commands. Shorter prefixes can be ambiguous if they match multiple targets.

```bash
node scripts/cdp.mjs list
# 6BE827FA  Google                   https://www.google.com
# 4A9F2E1C  Stack Overflow           https://stackoverflow.com

node scripts/cdp.mjs snap 6BE8    # Matches first tab
node scripts/cdp.mjs snap 4A9F    # Matches second tab
node scripts/cdp.mjs snap 4      # Ambiguous (too short)
```

--------------------------------

### Handle Navigation Errors (e.g., DNS Failure)

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

Example error message indicating a navigation failure reported by Chrome, such as a DNS resolution issue.

```text
Error: net::ERR_NAME_NOT_RESOLVED
```

--------------------------------

### Navigation and Network Timing Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Commands for navigating to URLs and retrieving network timing information for a specific tab.

```bash
cdp nav 6BE8 'https://example.com'
cdp net 6BE8
```

--------------------------------

### Take Screenshot

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Captures the current viewport of the browser at native resolution and saves it as a PNG image. The output path can be specified, otherwise a default path is used.

```APIDOC
## Take Screenshot

### Description
Capture the viewport at native resolution as PNG.

### Method
POST

### Endpoint
/cdp/screenshot

### Parameters
#### Request Body
- **args[0]** (string) - Optional - Output file path; if omitted, defaults to `screenshot-<targetId>.png` in runtime dir.

### Request Example
```json
{
  "id": 1,
  "cmd": "shot",
  "args": ["screenshot.png"]
}
```

### Response
#### Success Response (200 OK)
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - true if command succeeded.
- **result** (string) - Multi-line output with file path, DPR, and coordinate mapping instructions.

#### Response Example
```json
{
  "id": 1,
  "ok": true,
  "result": "/home/user/.cache/cdp/screenshot-6BE827FA.png\nScreenshot saved. Device pixel ratio (DPR): 2\nCoordinate mapping:\n  ..."
}
```

### Error Handling
If the command fails, the response will include an `error` field.

#### Error Response
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - false if command failed.
- **error** (string) - Error message.

#### Error Response Example
```json
{
  "id": 1,
  "ok": false,
  "error": "Failed to take screenshot."
}
```
```

--------------------------------

### Remove Stale Socket File

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Remove the stale socket file located at ~/.cache/cdp/cdp-*.sock to resolve EADDRINUSE errors when the daemon fails to start.

```bash
rm ~/.cache/cdp/cdp-*.sock
# Retry command
```

--------------------------------

### Get Accessibility Tree Snapshot

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Retrieve the accessibility tree of the current page. The output is a plain-text representation with indentation indicating hierarchy and ARIA roles.

```json
{"id": 1, "cmd": "snap", "args": []}
```

```json
{"id": 1, "ok": true, "result": "[document] Google\n  [navigation] ..."}
```

--------------------------------

### Load All Items with Pagination

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Repeatedly click a specified button to load more items, with a delay between clicks. This continues until the button is no longer present on the page.

```bash
node scripts/cdp.mjs loadall 6BE8 'button.load-more' 1500
# Repeatedly clicks button every 1500ms until it disappears
```

--------------------------------

### Get All Open Pages

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Fetches all open pages (targets) from Chrome, excluding internal chrome:// tabs. Returns an array of TargetInfo objects.

```javascript
async function getPages(cdp: CDP): Promise<TargetInfo[]>

const pages = await getPages(cdp);
console.log(pages.map(p => `${p.targetId.slice(0, 8)}: ${p.title}`));
```

--------------------------------

### Navigate to URL

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Navigate the browser to a specified URL and wait for the page to fully load. This command validates the URL protocol and waits for both the 'loadEventFired' and 'document.readyState === "complete"' events, with timeouts for each.

```json
{"id": 1, "cmd": "nav", "args": ["https://example.com"]}
```

```json
{"id": 1, "ok": true, "result": "Navigated to https://example.com"}
```

--------------------------------

### Take a screenshot

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Captures a screenshot of a specified target and saves it to a file. The device pixel ratio (DPR) is also reported.

```bash
node scripts/cdp.mjs shot 6BE8 /tmp/google.png
```

--------------------------------

### Daemon Mode IPC Request Format

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Specifies the newline-delimited JSON format for requests sent to the daemon mode Unix socket server. Includes an example of a command request.

```json
{ "id": 1, "cmd": "snap", "args": [] }
```

--------------------------------

### CDP Class Methods

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/PROJECT_OVERVIEW.md

Lists key methods available on the CDP class for managing connections, sending commands, and handling events.

```javascript
// Connect to Chrome's remote debugging WebSocket
async connect(wsUrl: string)

// Send a CDP command
send(method: string, params?: object, sessionId?: string): Promise<any>

// Subscribe to an event
onEvent(method: string, handler: Function): () => void

// Wait for event with timeout
waitForEvent(method: string, timeout?: number): { promise, cancel() }

// Register close handler
onClose(handler: Function)

// Close the connection
close()

```

--------------------------------

### List Pages Response (Success)

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

A successful response to the 'list' command includes an 'ok: true' field and a 'result' string containing a plain-text formatted list of pages.

```json
{"id": 1, "ok": true, "result": "6BE827FA  Google Chrome                                      https://www.google.com\n4A9F2E1C  Stack Overflow..."}
```

--------------------------------

### Get HTML Content by Selector

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Retrieves the HTML content of the entire page or a specific element matched by a CSS selector. If no selector is provided, the full page HTML is returned.

```javascript
async function htmlStr(cdp: CDP, sid: string, selector?: string): Promise<string>

const html = await htmlStr(cdp, sid, 'button.primary');
// Returns: "<button class="primary">Click me</button>"
```

--------------------------------

### Coordinate conversion hint

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Illustrates the relationship between screenshot image pixels and CSS pixels, emphasizing the role of DPR.

```text
CSS px = screenshot image px / DPR
```

--------------------------------

### Data Extraction Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Commands used for extracting data from the browser, including evaluating JavaScript, getting HTML content, and accessing the accessibility tree. These are useful for scraping and analysis.

```bash
cdp-skill browser eval "document.title"
cdp-skill browser html "#content"
cdp-skill browser snap "#main"
```

--------------------------------

### Open a new tab

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/skills/chrome-cdp/SKILL.md

Opens a new browser tab, optionally navigating to a specified URL. Each new tab requires explicit user approval.

```bash
scripts/cdp.mjs open    [url]
```

--------------------------------

### Get Network Resource Timing Information

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Retrieves resource timing information using the Performance API. Returns a formatted table of resources including duration, size, type, and name.

```javascript
async function netStr(cdp: CDP, sid: string): Promise<string>
```

--------------------------------

### Get HTML Content

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Use this command to retrieve the full HTML of a page or the HTML of a specific element identified by a CSS selector. If no selector is provided, the entire document's outerHTML is returned.

```json
{"id": 1, "cmd": "html", "args": ["button.primary"]}
```

```json
{"id": 1, "ok": true, "result": "<button class=\"primary\">Click me</button>"}
```

--------------------------------

### Navigate to URL

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Navigates the browser page to a specified URL and waits for the page load to complete.

```APIDOC
## Navigate to URL

### Description
Navigate the page to a URL and wait for load completion.

### Method
POST

### Endpoint
/nav

### Parameters
#### Request Body
- **id** (number) - Required - Unique identifier for the request.
- **cmd** (string) - Required - Command name, should be "nav".
- **args** (array) - Required - An array containing a single string element: the HTTP or HTTPS URL to navigate to.

### Request Example
```json
{
  "id": 1,
  "cmd": "nav",
  "args": ["https://example.com"]
}
```

### Response
#### Success Response (200 OK)
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - true if command succeeded.
- **result** (string) - Confirmation message, e.g., "Navigated to https://example.com".

#### Response Example
```json
{
  "id": 1,
  "ok": true,
  "result": "Navigated to https://example.com"
}
```

#### Error Response
- **id** (number) - Echoes the request ID.
- **ok** (boolean) - false if command failed.
- **error** (string) - Error message. Possible errors include:
  - "Invalid URL: ..."
  - "Only http/https URLs allowed, got: ..."
  - "<errorText>" (for navigation failures like DNS issues)
  - "Timed out waiting for navigation to finish"
```

--------------------------------

### getOrStartTabDaemon(targetId)

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Manages the lifecycle of a tab daemon process. It attempts to connect to an existing daemon for the specified target ID or starts a new one if none is found. The function includes retry logic for connection attempts.

```APIDOC
## getOrStartTabDaemon(targetId)

### Description
Connects to an existing daemon or spawns a new one if needed. Retries connection up to 20 times with 300ms delays between attempts.

### Signature
```javascript
async function getOrStartTabDaemon(targetId: string): Promise<net.Socket>
```

### Throws
- `Error` with message `"Daemon failed to start — did you click Allow in Chrome?"` if daemon socket cannot be reached
```

--------------------------------

### Element Interaction Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Commands for interacting with web elements, such as clicking, typing, and handling pagination.

```bash
cdp click 6BE8 '.selector'
cdp type 6BE8 'text'
cdp loadall 6BE8 '.load-more' 1500
```

--------------------------------

### Send Raw CDP Command

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

Use this command to send any valid Chrome DevTools Protocol command and get the raw JSON response. Ensure the CDP method name and optional JSON parameters are correctly formatted.

```json
{"id": 1, "cmd": "evalraw", "args": ["DOM.getDocument", "{}"]}
```

```json
{"id": 2, "cmd": "evalraw", "args": ["Page.getLayoutMetrics", "{}"]}
```

```json
{"id": 3, "cmd": "evalraw", "args": ["Runtime.enable", "{}"]}
```

--------------------------------

### Error: Ambiguous prefix

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

The provided prefix matches multiple target IDs, making it ambiguous. Use a longer prefix to uniquely identify the desired target.

```text
Error: Ambiguous prefix "6BE8" — matches 3 targets. Use more characters.
```

--------------------------------

### Page.navigate Method Signature

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/types.md

Parameters for navigating to a specific URL. Returns frame and loader IDs, and an optional error message.

```javascript
{
  url: string              // Destination URL
}
```

```javascript
{
  frameId: string,         // Frame ID
  loaderId: string,        // Loader ID (indicates if navigation occurred)
  errorText?: string       // Error message if navigation failed
}
```

--------------------------------

### Handle 'Element Not Found' Errors

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

When an element is not found, use a series of debugging steps. This includes taking screenshots, getting the accessibility tree and full HTML, and finally verifying the selector's existence with an eval command.

```bash
# Error: Element not found: .selector

# Debug steps:
# 1. Take a screenshot: node scripts/cdp.mjs shot 6BE8
# 2. Get accessibility tree: node scripts/cdp.mjs snap 6BE8
# 3. Get full HTML: node scripts/cdp.mjs html 6BE8
# 4. Verify selector exists: node scripts/cdp.mjs eval 6BE8 'document.querySelector(".selector") ? "found" : "not found"'
```

--------------------------------

### Error: Unknown command

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

This error occurs when an unrecognized command is provided to the CLI. Use `cdp help` to see a list of available commands.

```text
Error: Unknown command: foobar

Usage: cdp <command> [args]
  list
  snap <target>
  ...
```

--------------------------------

### Get Chrome DevTools WebSocket URL

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Reads Chrome's DevToolsActivePort file to automatically detect and return the WebSocket URL for remote debugging. Supports multiple browsers and operating systems, and honors the CDP_PORT_FILE environment variable.

```javascript
function getWsUrl(): string
```

```javascript
const wsUrl = getWsUrl();
// Returns: "ws://127.0.0.1:9222/devtools/browser/abc123def456..."
```

--------------------------------

### Optimize Batch Operations with Bash

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Run multiple commands sequentially on the same target to reuse the daemon process and avoid startup overhead.

```bash
# Inefficient: spawns daemon twice
node scripts/cdp.mjs eval 6BE8 'expr1'
node scripts/cdp.mjs eval 6BE8 'expr2'

# Better: daemon persists between commands
node scripts/cdp.mjs eval 6BE8 'expr1'
# daemon active
node scripts/cdp.mjs eval 6BE8 'expr2'
# reuses daemon
```

--------------------------------

### Error: Daemon: cannot connect to Chrome

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/errors.md

The daemon process is unable to establish a WebSocket connection to Chrome. Verify that Chrome is running and not in the process of shutting down.

```text
Daemon: cannot connect to Chrome: ECONNREFUSED
```

--------------------------------

### Advanced CDP Commands

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/README.md

Commands for retrieving HTML, executing raw CDP methods, opening new tabs, and stopping the daemon.

```bash
cdp html 6BE8 [selector]
cdp evalraw 6BE8 'Method' [json]
cdp open [url]
cdp stop [6BE8]
```

--------------------------------

### Load All Command Response (Success)

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/endpoints.md

A successful response to the 'loadall' command includes the request ID, a boolean 'ok' field set to true, and a result string indicating the number of times the element was clicked.

```json
{"id": 1, "ok": true, "result": "Clicked \"button.load-more\" 15 time(s) until it disappeared"}
```

--------------------------------

### Configure Socket Permissions

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/configuration.md

Sets restrictive permissions for Unix sockets to prevent unauthorized access. Ensure this runs before creating directories.

```javascript
if (!IS_WINDOWS) process.umask(0o077);
mkdirSync(RUNTIME_DIR, { mode: 0o700 });
```

--------------------------------

### snapshotStr

Source: https://github.com/pasky/chrome-cdp-skill/blob/main/_autodocs/api-reference/cdp-cli.md

Generates a plain text representation of the page's accessibility tree. Optionally filters out InlineTextBox nodes for brevity.

```APIDOC
## snapshotStr(cdp, sid, compact?)

### Description
Generates an accessibility tree snapshot of the page.

### Parameters
#### Path Parameters
- **cdp** (CDP) - Required - Connected CDP client
- **sid** (string) - Required - Session ID for the target tab
- **compact** (boolean) - Optional - If true, filters out `InlineTextBox` nodes for brevity

### Returns
Plain text representation of the accessibility tree

### Example
```javascript
const tree = await snapshotStr(cdp, sessionId, true);
console.log(tree);
// Output:
// [document] Google Search
//   [navigation] Site Navigation
//     [link] Search — Visit Google Search
//     [link] Maps — Visit Google Maps
//   [region] Main
//     [searchbox] Search = "query"
```
```