cdp-attach

What this skill does

# CDP Attach

Attach to a running Chrome DevTools Protocol instance. Immune to frozen-tab timeouts.

## Prerequisites

A **visible** (headed) CDP-enabled browser must be running. Headless instances are blocked — silent execution without user visibility is a security risk.

```bash
# Manual launch (visible browser)
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
```

> **Note**: `claude --chrome` may launch a headless instance. If `v1 version` shows `HeadlessChrome`, use the manual launch method above instead.

## Scope Guard

cdp-attach is for **acting on** the attached browser, not for **researching through** it.

**WILL** use cdp-attach for:
- Capturing current state (screenshot, snapshot, network/console logs)
- Interacting with attached page (click, fill, JS evaluate, dialog handling)
- Navigating as a workflow step (e.g., form submit → result page, SPA state transitions)
- Monitoring (network_start/stop, console, performance tracing)
- Error diagnosis (screenshot + Read of error pages during automation)
- API response debugging (navigate to endpoint as part of debugging workflow)

**WILL NOT** use cdp-attach for:
- Browsing documentation or API references
- Searching for information via web pages
- Opening new tabs to research topics
- Reading web content for knowledge gathering

**Litmus test**: "Am I acting on the page, or learning from it?"
If learning → switch to Tavily MCP (`tavily_search`, `tavily_extract`) or Prothesis for multi-perspective investigation.

**Redirect rule**: When a research need arises mid-workflow, pause the cdp-attach context, resolve via Tavily, then resume cdp-attach with the findings.

## Execution

Each Bash call is a separate shell. Always combine the variable assignment with the command:
```bash
V1="${CLAUDE_PLUGIN_ROOT}/scripts/v1_core.py" && $V1 list
V2="${CLAUDE_PLUGIN_ROOT}/scripts/v2_interact.py" && $V2 click --selector "a"
V3="${CLAUDE_PLUGIN_ROOT}/scripts/v3_advanced.py" && $V3 network_start
```

## Quick Reference

### v1 — Core (`v1_core.py`)

```bash
V1="${CLAUDE_PLUGIN_ROOT}/scripts/v1_core.py"

$V1 version                                    # Browser info
$V1 list                                       # List tabs (default: first 50 pages)
$V1 list --search "github" --limit 20          # Search tabs
$V1 list --type all                            # Include iframes, workers
$V1 select 0                                   # Select tab by index
$V1 select AB71CD183BCE05DD...                  # Select by target ID
$V1 screenshot                                 # PNG of selected tab
$V1 screenshot --full-page --format jpeg -o /tmp/page.jpg
$V1 snapshot --depth 3                         # Accessibility tree
$V1 evaluate "document.title"                  # Run JavaScript
$V1 evaluate "fetch('/api').then(r=>r.json())" --await
$V1 evaluate --stdin <<< 'var x = document.title; x'  # Stdin mode
$V1 evaluate --no-rewrite "const x = 1"       # Skip var rewriting
$V1 navigate "https://example.com"             # Navigate
$V1 navigate "https://example.com" --wait-for none
$V1 reload                                     # Reload current page (wait for load)
$V1 reload --hard                              # Bypass cache (Page.reload ignoreCache=true)
$V1 back                                       # Navigate back (default: no wait — bfcache may skip load event)
$V1 forward                                    # Navigate forward (default: no wait)
$V1 back --wait-for load                       # Opt-in load wait (use when fresh load expected)

$V1 evaluate "document.title" --frame "iframe.embedded"   # Evaluate inside an iframe
$V1 evaluate --frame main "location.href"                 # Explicit top frame
$V1 evaluate --frame-url "youtube" "location.href"        # Match frame by URL substring

$V1 wait --selector "div.loaded" --timeout-ms 10000       # Element appears
$V1 wait --text "Order complete"                          # Text appears somewhere
$V1 wait --url-contains "/dashboard"                      # URL navigation
$V1 wait --load-state networkidle                         # Page lifecycle state
$V1 wait --function "window.__APP_READY__ === true"       # Custom JS predicate

$V1 doctor                                                # 7-step diagnostic (HTTP/WS/eval/cache)
$V1 cdp_call Page.getLayoutMetrics                        # Raw CDP escape hatch (no params)
$V1 cdp_call Storage.getCookies --params-json '{"urls":["https://example.com"]}'
$V1 cdp_call DOM.getDocument --stdin <<< '{"depth":1}'    # Read params from stdin
$V1 error_list                                            # Recent CDP errors (last 50)
$V1 error_list --filter "Network" --limit 20              # Filter category/method/error
$V1 error_list --since-seconds 300                        # Last 5 minutes only
```

> **Note on `--frame`**: accepts a CSS selector matching a frame owner (e.g. `iframe`, `frame`, `object`, `embed`) or the literal `main` for the top-level document. Cross-origin frames resolve the same way because CDP exposes per-frame execution contexts regardless of origin.

> **Note on `doctor`, `cdp_call`, `error_list`**: bypass the headless guard so they run on any reachable CDP endpoint. `doctor` reports headless state itself; `cdp_call` is the escape hatch for CDP methods not wrapped by v1/v2/v3; `error_list` reads `~/.cache/cdp-attach/errors.jsonl`, which `cdp_client.send()` populates automatically on every CDP failure (CDP error response, timeout, or WebSocket error). Disable error logging with `CDP_ATTACH_NO_ERROR_LOG=1`. The file rotates to `errors.jsonl.1` at 1MB.

### Common Mistakes

**Commands that do NOT exist:**
- `read_screenshot` — use `v1 screenshot` then `Read /tmp/cdp-screenshot-*.png`

**Arguments that do NOT exist:**
- `click --coordinates x y` — use positional: `click 100 200`
- `click --text "..."` — use `click --selector` with a CSS selector instead
- `screenshot --selector` — not supported; screenshot captures the full viewport (or `--full-page`)
- `find_element --id` — use `--node-id` or `--backend-node-id` in `get_bounds`
- `scan_interactive --selector` — not supported; use `find_element --selector` instead
- `get_bounds --text` — use `find_element --text` first, then `get_bounds --node-id`

**JavaScript in evaluate:**
- `const`/`let` are auto-rewritten to `var` by default (prevents re-declaration errors on repeated calls). Use `--no-rewrite` to disable.
- For complex JS with quotes/backticks, use `--stdin` with heredoc:
  ```bash
  $V1 evaluate --stdin <<'JS'
  document.querySelectorAll('a').forEach(a => console.log(a.href))
  JS
  ```
- Use `--await` flag for promises (auto-wraps in async IIFE if needed):
  ```bash
  $V1 evaluate --await "await fetch('/api').then(r => r.json())"
  ```
- The single-line auto-wrap inserts a `return`. Multi-line bodies (anything containing `;` or a newline) are wrapped without `return` — write the `return` yourself:
  ```bash
  $V1 evaluate --await --stdin <<'JS'
  var r = await fetch('/api');
  var t = await r.text();
  return t;          # required — otherwise the result is undefined
  JS
  ```

### v2 — Interaction (`v2_interact.py`)

```bash
V2="${CLAUDE_PLUGIN_ROOT}/scripts/v2_interact.py"

$V2 click 100 200                              # Click at coordinates
$V2 click --selector "button.submit"           # Click CSS selector
$V2 click 100 200 --button right               # Right-click (context menu)
$V2 click 100 200 --clicks 2                   # Double-click (text selection)
$V2 click --selector "a" --modifiers ctrl      # Ctrl+click (new tab on link)
$V2 scroll                                     # Scroll page down 300px (viewport center)
$V2 scroll --delta-y -500                      # Scroll up 500px
$V2 scroll 100 400 --delta-y 200               # Scroll at specific coordinates
$V2 scroll --selector "div.scrollable" --delta-y 100
$V2 fill --selector "input[name=q]" "search query"
$V2 upload_file --selector "input[type=file]"