Chrome DevTools

Browser automation via Puppeteer scripts with persistent sessions. All scripts output JSON.

Skill Location

Skills can be project-scope (.claude/skills/chrome-devtools/scripts/) or user-scope ($HOME/.claude/skills/chrome-devtools/scripts/). Project-scope wins when both exist. Scripts use __dirname for paths — no need to cd first.

Choosing Your Approach

Project-Specific Setup

For project-specific connection patterns and when to prefer chrome-devtools over agent-browser, see process/context/tests/all-tests.md in the consuming repo. This file is a generic tool reference.

Browser Mode

Auto-resolved by resolveHeadless() in lib/browser.js:

Override per-script with --headless true|false.

ARIA Snapshot (Element Discovery)

# Stdout
node "$SKILL_DIR/aria-snapshot.js" --url https://example.com

# Save to file
node "$SKILL_DIR/aria-snapshot.js" --url https://example.com --output ./snap.yaml

YAML output format:

- banner:
  - link "Hacker News" [ref=e1]
- main:
  - textbox [ref=e10]
    /placeholder: "Search"

[ref=eN] is a stable identifier you can pass to select-ref.js --action click|fill|text|screenshot|hover|focus.

Local HTML Files

Never browse file:// URLs — many browser features are blocked. Serve via local HTTP first:

npx serve ./dist -p 3000 &
node "$SKILL_DIR/navigate.js" --url http://localhost:3000

Quick Start

# One-time setup
npm install --prefix "$SKILL_DIR"

# Linux/WSL only: install Chrome system libs
"$SKILL_DIR/install-deps.sh"

# Test (browser stays running for session reuse)
node "$SKILL_DIR/navigate.js" --url https://example.com
# Output: {"success": true, "url": "...", "title": "..."}

Session Persistence

Browser state persists via .browser-session.json (WebSocket endpoint file). Default: scripts disconnect but keep browser running.

# First script: launch + navigate (browser stays running)
node "$SKILL_DIR/navigate.js" --url https://example.com/login

# Subsequent scripts: reuse page state
node "$SKILL_DIR/fill.js" --selector "#email" --value "user@example.com"
node "$SKILL_DIR/fill.js" --selector "#password" --value "secret"
node "$SKILL_DIR/click.js" --selector "button[type=submit]"

# End session
node "$SKILL_DIR/navigate.js" --url about:blank --close true

Workflow Loop

1. Execute focused script for single task
2. Observe JSON output
3. Assess completion status
4. Decide next action
5. Repeat until done

Screenshots

node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./page.png
node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./page.png --full-page true
node "$SKILL_DIR/screenshot.js" --url https://example.com --selector ".main" --output ./el.png

Screenshots >5MB auto-compress via Sharp. Use --max-size 3 for a lower threshold, --no-compress to disable.

Console + Network Capture

# Console: capture errors for 5s
node "$SKILL_DIR/console.js" --url https://example.com --types error --duration 5000

# Network: 4xx/5xx response scan
node "$SKILL_DIR/network.js" --url https://example.com | jq '.requests[] | select(.response.status >= 400)'

Common Patterns

Web scraping — use evaluate.js to run JS in page context, return JSON. Form automation — navigate.js → fill.js → click.js. Performance — performance.js returns Core Web Vitals.

Error Recovery

1. Capture current state with screenshot.js (don't navigate — preserve state)
2. Get console errors with console.js
3. Discover correct selector with snapshot.js (or aria-snapshot.js)
4. Try XPath if CSS fails: click.js --selector "//button[contains(text(),'Submit')]"

Authentication

Five methods (use the right one for the auth flow):

Auth sessions save to .auth-session.json (24h reuse). For the full contract of each method including the Chrome remote-debugging launch commands by OS, see references/authentication.md (extracted from the prior SKILL.md body).

Available Scripts

The 15+ scripts in scripts/ (navigate, click, fill, evaluate, snapshot, aria-snapshot, select-ref, console, network, performance, ws-debug, ws-full-debug, inject-auth, import-cookies, connect-chrome) are documented in references/scripts.md with per-script options. Load that file when you need exact flags.

Reference Documentation

• ./references/cdp-domains.md — Chrome DevTools Protocol domains
• ./references/puppeteer-reference.md — Puppeteer API patterns
• ./references/performance-guide.md — Core Web Vitals optimization
• ./references/scripts.md — Per-script option reference
• ./references/authentication.md — Full auth method contract
• ./scripts/README.md — Detailed script options
• ./references/browserbase-cloud-setup.md — Browserbase cloud browser setup