# Faster Chrome Devtools Skill

> Control Chrome directly via DevTools Protocol with snapshots, clicks, waits, and screenshots

- Skill: `aradotso/faster-chrome-devtools-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/faster-chrome-devtools-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/faster-chrome-devtools-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/faster-chrome-devtools-skill

---


# faster-chrome-devtools-skill

> Skill by [ara.so](https://ara.so) — Devtools Skills collection.

An agent skill and CLI for controlling Chrome directly through the Chrome DevTools Protocol (CDP). Provides fast accessibility snapshots, element interaction, navigation with explicit timeouts, screenshot capture, and console/network inspection without heavy dependencies like Puppeteer or Playwright.

## Installation

Install globally for all agents:

```sh
npx skills add zeke/faster-chrome-devtools-skill --global --all --yes
```

Requires Node.js installed. No additional dependencies needed.

## Core Concepts

The tool uses a lightweight background daemon that holds the CDP WebSocket connection open for 20 minutes, avoiding repeated Chrome access prompts. Connection details are stored in an owner-readable temp file with a random auth token.

**Three connection modes:**

1. **Logged-in Chrome**: Connect to your existing Chrome instance (requires enabling remote debugging at `chrome://inspect/#remote-debugging`)
2. **Anonymous Chromium**: Launch a fresh temporary instance with `--launch`
3. **Remote/Cloud**: Connect to Cloudflare Browser Run or other remote endpoints

## CLI Commands

All commands use `node scripts/cdp.mjs <command>` format.

### Navigation & Page Control

```bash
# Navigate to URL with explicit timeout
node scripts/cdp.mjs navigate https://example.com --timeout 10000

# Navigate and wait for specific text
node scripts/cdp.mjs navigate https://github.com --wait-text "Pull requests"

# Navigate and wait for selector
node scripts/cdp.mjs navigate https://example.com --wait-selector "#main-content"

# List all open tabs
node scripts/cdp.mjs list-tabs

# Open new tab
node scripts/cdp.mjs open-tab https://news.ycombinator.com

# Switch to existing tab by ID
node scripts/cdp.mjs switch-tab <tab-id>

# Close current tab
node scripts/cdp.mjs close-tab
```

### Reading Page Content

```bash
# Get compact accessibility snapshot with stable element references
node scripts/cdp.mjs snapshot

# Get full page text content
node scripts/cdp.mjs get-text

# Capture screenshot (JPEG by default for compression)
node scripts/cdp.mjs screenshot --path screenshot.jpg

# Capture WebP screenshot
node scripts/cdp.mjs screenshot --path screenshot.webp --format webp

# Capture PNG screenshot
node scripts/cdp.mjs screenshot --path screenshot.png --format png

# Full page screenshot
node scripts/cdp.mjs screenshot --path full.jpg --full-page
```

### Element Interaction

```bash
# Click by accessibility reference (from snapshot)
node scripts/cdp.mjs click --ref "button-login-123"

# Click by CSS selector
node scripts/cdp.mjs click --selector "button.submit"

# Fill input by accessibility reference
node scripts/cdp.mjs fill --ref "input-email-456" --value "user@example.com"

# Fill input by CSS selector
node scripts/cdp.mjs fill --selector "#email" --value "user@example.com"

# Type text (works in cross-origin frames via native CDP)
node scripts/cdp.mjs type "Hello world" --delay 50
```

### Wait Operations

```bash
# Wait for text to appear (default 30s timeout)
node scripts/cdp.mjs wait-text "Success" --timeout 15000

# Wait for selector to exist
node scripts/cdp.mjs wait-selector ".results-loaded"

# Wait for specific duration
node scripts/cdp.mjs wait --duration 2000
```

### Debugging & Inspection

```bash
# Get console messages
node scripts/cdp.mjs get-console

# Get failed network requests
node scripts/cdp.mjs get-failed-loads

# Evaluate JavaScript
node scripts/cdp.mjs eval "document.title"

# Execute multi-line JavaScript
node scripts/cdp.mjs eval "
const links = Array.from(document.querySelectorAll('a'));
return links.map(a => ({ text: a.textContent, href: a.href }));
"

# Call raw CDP method
node scripts/cdp.mjs raw Runtime.evaluate '{"expression": "navigator.userAgent"}'
```

### Connection Management

```bash
# Launch anonymous Chrome instance
node scripts/cdp.mjs snapshot --launch

# Connect to specific WebSocket endpoint
node scripts/cdp.mjs snapshot --ws-endpoint ws://localhost:9222/devtools/browser/xyz

# Connect to HTTP endpoint (auto-discovers WebSocket)
node scripts/cdp.mjs snapshot --http-endpoint http://localhost:9222

# Stop the daemon
node scripts/cdp.mjs stop

# Stop specific daemon by ID
node scripts/cdp.mjs stop --id <daemon-id>

# Stop all running daemons
node scripts/cdp.mjs stop --all

# Stop daemon for specific endpoint
node scripts/cdp.mjs stop --ws-endpoint ws://localhost:9222/devtools/browser/xyz
```

## Configuration

### Using Your Logged-in Chrome

1. Open Chrome and navigate to `chrome://inspect/#remote-debugging`
2. Check "Discover network targets" 
3. Click "Configure" and ensure `localhost:9222` is listed
4. Launch Chrome with remote debugging:

```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
```

### Cloudflare Browser Run Setup

Set these environment variables:

```bash
export CLOUDFLARE_ACCOUNT_ID="your-account-id"
export CLOUDFLARE_API_TOKEN="your-api-token"
```

Then use:

```bash
node scripts/cdp.mjs snapshot --http-endpoint https://browser.run.cloudflare.com
```

The CLI automatically adds the required authentication headers.

## Common Patterns

### Scrape Structured Data

```javascript
// 1. Navigate and wait for content
// node scripts/cdp.mjs navigate https://news.ycombinator.com --wait-selector ".itemlist"

// 2. Get accessibility snapshot to find element references
// node scripts/cdp.mjs snapshot

// 3. Extract data with JavaScript
// node scripts/cdp.mjs eval "
const stories = Array.from(document.querySelectorAll('.athing')).slice(0, 5);
return stories.map(story => ({
  title: story.querySelector('.titleline > a')?.textContent,
  url: story.querySelector('.titleline > a')?.href
}));
// "
```

### Login Flow

```bash
# Navigate to login page
node scripts/cdp.mjs navigate https://example.com/login --wait-selector "#username"

# Fill credentials
node scripts/cdp.mjs fill --selector "#username" --value "$USERNAME"
node scripts/cdp.mjs fill --selector "#password" --value "$PASSWORD"

# Submit form
node scripts/cdp.mjs click --selector "button[type=submit]"

# Wait for redirect
node scripts/cdp.mjs wait-text "Dashboard" --timeout 10000

# Take screenshot to verify
node scripts/cdp.mjs screenshot --path logged-in.jpg
```

### Multi-tab Workflow

```bash
# List current tabs
node scripts/cdp.mjs list-tabs

# Open new tab
node scripts/cdp.mjs open-tab https://github.com

# Work in new tab
node scripts/cdp.mjs snapshot

# Switch back to first tab
node scripts/cdp.mjs switch-tab <first-tab-id>

# Close current tab when done
node scripts/cdp.mjs close-tab
```

### Monitor Page for Changes

```bash
# Navigate to page
node scripts/cdp.mjs navigate https://example.com/status

# Take initial snapshot
node scripts/cdp.mjs snapshot > before.txt

# Wait some time
node scripts/cdp.mjs wait --duration 5000

# Take second snapshot
node scripts/cdp.mjs snapshot > after.txt

# Compare with diff tool
diff before.txt after.txt
```

### Debugging Failed Loads

```bash
# Navigate to page
node scripts/cdp.mjs navigate https://example.com

# Check for failed network requests
node scripts/cdp.mjs get-failed-loads

# Check console errors
node scripts/cdp.mjs get-console

# Take screenshot for visual inspection
node scripts/cdp.mjs screenshot --path debug.jpg
```

## Accessibility Snapshot Format

The `snapshot` command returns a compact tree with stable references:

```json
{
  "role": "WebArea",
  "name": "Example Page",
  "ref": "page-1",
  "children": [
    {
      "role": "button",
      "name": "Submit",
      "ref": "button-submit-42",
      "focusable": true
    },
    {
      "role": "textbox",
      "name": "Email",
      "ref": "input-email-43",
      "focusable": true,
      "value": ""
    }
  ]
}
```

Use the `ref` values with `--ref` flags in `click` and `fill` commands for reliable element targeting.

## Troubleshooting

### "Connection refused" when connecting to Chrome

- Ensure Chrome is running with `--remote-debugging-port=9222`
- Check that no firewall is blocking localhost:9222
- Verify `chrome://inspect/#remote-debugging` shows the debugging port

### "Target closed" or connection drops

- The daemon times out after 20 minutes of inactivity
- Restart with any command that reconnects
- Use `node scripts/cdp.mjs stop` to clean up stale daemons

### Screenshots are empty or broken

- Wait for page to fully load before capturing
- Use `--wait-selector` or `--wait-text` with navigate
- Try `--full-page` flag if content is below fold
- Check console/failed loads for rendering errors

### Elements not found by selector

- Use `snapshot` first to get stable accessibility references
- Prefer `--ref` over `--selector` for reliability
- Use `wait-selector` before clicking/filling
- Check that selector syntax is correct for the page's structure

### Cloudflare Browser Run authentication fails

- Verify `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` are set
- Check token has Browser Rendering permissions
- Ensure endpoint URL is `https://browser.run.cloudflare.com`

### Commands hang or timeout

- Increase `--timeout` values for slow pages
- Check network connectivity to target site
- Use `get-console` and `get-failed-loads` to diagnose page errors
- Try navigating to simpler test page first to verify connection