devtools-ai

Give AI coding agents eyes on browser DevTools.

devtools-ai is a CLI middleware tool that launches a headless browser, navigates to one or more URLs, captures network traffic and console output, and writes a structured report that AI coding agents can consume. Use it to diagnose runtime errors, failed API calls, and visual issues without opening a browser manually.

Install

npm install -g devtools-ai

Chromium is downloaded automatically on first run via Playwright.

Quick Start

1. Check for errors on a local dev server:

devtools-ai run http://localhost:3000 --preset errors

2. Take a screenshot after clicking a button:

devtools-ai run http://localhost:3000 --preset visual --click "#login-btn"

3. Flag slow API responses and output raw JSON:

devtools-ai run http://localhost:3000/api/users --json --slow 500

Presets

Presets are named flag bundles that match common debugging scenarios. Use --preset <name> and override individual flags as needed.

| Preset | Use when... | What it captures | |----------------|-------------------------------------|--------------------------------------------------------------| | errors | App crashes or API returns errors | 4xx/5xx responses + console errors, no response bodies | | console-only | Debugging JS exceptions | All console output, no network bodies | | visual | Checking if UI renders correctly | Screenshot + console errors, no network bodies | | api-debug | Debugging API request/response data | 4xx/5xx on /api/* routes with full response bodies | | full | Need everything | All network, all console, screenshot, full bodies |

Flag Reference

Capture Control

| Flag | Default | Description | |-------------------------------|-------------------------------|--------------------------------------------------------------| | --preset <name> | none | Use a preset: errors, console-only, visual, api-debug, full | | --filter <codes> | all | Status codes to capture: 4xx,5xx, 400,500, all, none| | --route <pattern> | * | URL path filter: /api/*, /auth/** | | --console <levels> | error,warn | Console levels: error, warn,error,log, all | | --no-bodies | false | Strip response bodies from output (saves tokens) | | --console-only | false | Only capture console output, skip network entirely | | --screenshot | false | Save a PNG screenshot, path included in output | | --max-body <bytes> | 10240 | Truncate response bodies beyond this size | | --block-resources <types> | stylesheet,image,font,media | Block these resource types from loading | | --timeout <ms> | 5000 | Max wait time after navigation (ms) | | --slow <ms> | none | Flag requests slower than this threshold (ms) | | --json | false | Output raw JSON instead of XML-wrapped format |

Interaction

| Flag | Description | |----------------------|--------------------------------------------------------------| | --click <selector> | Click an element by CSS selector (repeatable) | | --eval <js> | Execute JavaScript on the page (repeatable) |

Execution order: navigate, wait, clicks (in order), evals (in order), extra wait, capture.

Use multiple --click and --eval flags for multi-step interactions:

devtools-ai run http://localhost:3000 \
  --click "#username" \
  --eval "document.querySelector('#username').value='test'" \
  --click "#submit"

Wait Strategies

| Flag | Description | |-------------------------------|--------------------------------------------------------------| | --wait-for networkidle | Wait until no network requests for 500ms (default) | | --wait-for load | Wait for window load event | | --wait-for domcontentloaded | Wait for DOMContentLoaded event | | --wait-for selector::<sel> | Wait until a CSS selector matches an element | | --wait-for-console <pattern>| Wait until a console message contains this string |

Browser and Request Configuration

| Flag | Default | Description | |--------------------|-------------|--------------------------------------------------------------| | --viewport <WxH> | 1280x720 | Browser viewport size | | --headers <json> | {} | Extra HTTP headers as a JSON string | | --cookie <value> | none | Cookie to set before navigation | | --no-redact | false | Disable PII/token redaction (local debugging only) | | --output <dir> | .devtools-ai/| Output directory | | --config <path> | .devtools-ai.config.json | Config file path |

Multi-URL Support

Capture multiple pages in a single session by passing multiple URLs:

devtools-ai run http://localhost:3000 http://localhost:3000/about http://localhost:3000/api/health

Each URL is navigated in sequence. Network and console output from all pages is combined into a single report.

Config File

Create a .devtools-ai.config.json file in your project root to set defaults, headers, cookies, and auth flows. Generate a starter config with:

devtools-ai config init

Full Example

{
  "defaults": {
    "filter": "4xx,5xx",
    "route": "/api/*",
    "console": "error,warn",
    "timeout": 8000,
    "waitFor": "networkidle",
    "maxBody": 20480,
    "blockResources": ["stylesheet", "image", "font", "media"],
    "viewport": "1920x1080",
    "output": ".devtools-ai/"
  },
  "redaction": {
    "enabled": true,
    "patterns": {
      "emails": true,
      "ipv4": true,
      "jwts": true
    },
    "headerRedact": ["authorization", "cookie", "set-cookie"]
  },
  "headers": {
    "X-Custom-Header": "my-value"
  },
  "cookies": ["session=abc123; Path=/; Domain=localhost"],
  "auth": {
    "url": "http://localhost:3000/login",
    "steps": [
      { "action": "fill", "selector": "#email", "value": "[email protected]" },
      { "action": "fill", "selector": "#password", "value": "password123" },
      { "action": "click", "selector": "#login-btn" },
      { "action": "wait", "strategy": "networkidle" }
    ]
  }
}

CLI flags always take priority over config file defaults.

Auth Flows

Authentication is configured exclusively through the config file (not CLI flags). When an auth block is present, devtools-ai navigates to the auth URL and executes the steps in order before proceeding to the target URL(s).

Supported step actions:

| Action | Fields | Description | |---------|----------------------|----------------------------------------------| | fill | selector, value | Type a value into an input field | | click | selector | Click an element | | wait | strategy | Wait using a strategy (e.g., networkidle) | | eval | value | Execute arbitrary JavaScript |

Example: Login Before Capture

{
  "auth": {
    "url": "http://localhost:3000/login",
    "steps": [
      { "action": "fill", "selector": "#email", "value": "[email protected]" },
      { "action": "fill", "selector": "#password", "value": "secret" },
      { "action": "click", "selector": "button[type=submit]" },
      { "action": "wait", "strategy": "networkidle" }
    ]
  }
}

After auth completes, session cookies are preserved for all subsequent URL navigations.

Output Format

By default, output is a JSON object wrapped in randomized XML tags, written to .devtools-ai/latest.xml. The XML wrapping prevents AI models from confusing the report with their own output.

Use --json to output raw JSON without XML wrapping (written to .devtools-ai/latest.json).

Structure

{
  "devtools_ai": {
    "session": { ... },
    "network": [ ... ],
    "console": [ ... ],
    "summary": { ... },
    "screenshot_path": "..."
  }
}

The output file path is printed to stdout so the invoking agent can locate and read it.

Commands

| Command | Description | |----------------------------|----------------------------------------------| | devtools-ai run <urls...> | Capture network and console from one or more URLs | | devtools-ai describe | Print a machine-readable capabilities document | | devtools-ai config init | Generate a starter config file |

License

Commercial license. 2 seats per license (one work machine, one personal machine). See LICENSE for full terms. Purchase at devtoolsai.gumroad.com/l/ijdql.