web-browser

tkersey's avatarfrom tkersey

Automate Chrome/Chromium via CDP: navigate, click, fill forms, evaluate JS, screenshot, scrape.

⭐30stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill enables comprehensive automation of Chrome and Chromium browsers via the Chrome DevTools Protocol (CDP). It empowers AI agents to perform complex web tasks including navigation, element interaction, JavaScript execution, and visual data capture, bridging the gap between LLMs and live web environments for real-time data access and UI manipulation.

Use Cases

  • Web Scraping & Data Extraction: Efficiently extract structured data from dynamic websites and Single Page Applications (SPAs) by navigating pages and evaluating JavaScript to retrieve specific content.
  • Automated UI Testing & QA: Validate web interfaces and perform smoke testing by simulating user clicks, form entries, and capturing screenshots for visual verification and debugging.
  • Workflow Automation: Streamline repetitive browser-based tasks such as filling out complex forms, navigating multi-step login flows, and interacting with web-based productivity tools.
  • Visual Monitoring & Auditing: Capture high-quality screenshots of web pages to monitor layout changes, verify visual consistency across different states, or document web content for compliance.
nameweb-browser
description"Automate Chrome/Chromium via CDP: navigate, click, fill forms, evaluate JS, screenshot, scrape."

Web Browser

When to use

  • Navigate or interact with live websites.
  • Click buttons, fill forms, or extract page content.
  • Evaluate JavaScript in a real browser context.
  • Capture screenshots for debugging or review.
  • UI validation and smoke testing in a real browser.

Requirements

  • Run commands from codex/skills/web-browser/ (so ./tools/*.js resolves).
  • Node.js (ESM + top-level await) and repo deps installed (notably puppeteer-core).
  • Chrome/Chromium installed, or set CODEX_CHROME_PATH.

Quick start

# Start Chrome with CDP on :9222
./tools/start.js

# Safer (recommended on your laptop): avoid killing an existing Chrome session
./tools/start.js --no-kill

# Open a deterministic tab, then operate on it
./tools/nav.js https://example.com --new
./tools/eval.js 'document.title'
./tools/screenshot.js

Loop: take small steps → inspect state (eval.js / screenshot.js) → repeat.

Configuration

  • Flags
    • start.js: --port, --user-data-dir, --chrome-path, --profile, --no-kill
    • nav.js / eval.js / screenshot.js / pick.js: --port, --browser-url
  • Environment
    • CODEX_BROWSER_URL: CDP URL (used when no CLI --port/--browser-url)
    • CODEX_BROWSER_PORT (alias: CODEX_CDP_PORT): CDP port for localhost
    • CODEX_BROWSER_USER_DATA_DIR: Chrome user data dir (used by start.js)
    • CODEX_CHROME_PATH (aliases: CHROME_PATH, PUPPETEER_EXECUTABLE_PATH): Chrome/Chromium executable

Targeting (active tab)

All tools operate on the “active tab”, defined as the last page returned by puppeteer.pages() (roughly: the most recently opened tab).

  • Prefer ./tools/nav.js <url> --new when you want deterministic targeting.
  • If actions hit the “wrong” tab, close extra tabs or open a fresh one.

Common commands

# See all options (safe; does not start/kill Chrome)
./tools/start.js --help

# Use a non-default port
./tools/start.js --port 9223 --no-kill
./tools/nav.js --port 9223 https://example.com --new

# Or configure once via env
export CODEX_BROWSER_URL=http://localhost:9223
./tools/eval.js 'document.title'

# Wait for a selector (polling with timeout; good for SPAs)
./tools/eval.js '(async () => { for (let i = 0; i < 50; i++) { const el = document.querySelector("button[type=submit]"); if (el) return true; await new Promise(r => setTimeout(r, 100)); } return false; })()'

# Screenshot current viewport
# Prints a PNG filepath in your system temp dir
./tools/screenshot.js

# Pick elements interactively
# Prints tag/id/class/text/html/parents for one element (or many via Cmd/Ctrl+click)
./tools/pick.js "Click the submit button"

Tip: use pick.js to inspect attributes/text, then craft a selector for eval.js.

Recipes

# Scrape structured data (return an array of objects for readable output)
./tools/eval.js 'Array.from(document.querySelectorAll("a"), a => ({ href: a.href, text: a.textContent?.trim() }))'
  • Login flows
    • Dedicated automation profile: run ./tools/start.js, log in once, then reuse the persisted profile in your user-data-dir (default: ~/.cache/scraping).
    • Default-profile bootstrap: run ./tools/start.js --profile when you truly need existing cookies/logins.

Security & privacy

  • ./tools/start.js --profile uses rsync -a --delete to copy your default Chrome profile into your user-data-dir (cookies/sessions/PII).
  • Treat your user-data-dir (default: ~/.cache/scraping) as sensitive; avoid on shared machines and delete it when done if needed.

Troubleshooting

  • ✗ Failed to connect to Chrome via CDP: run ./tools/start.js (or set CODEX_BROWSER_URL/--port to match your Chrome).
  • ✗ No active tab found: open a page first (e.g., ./tools/nav.js https://example.com --new).
  • Port 9222 is busy: pick a new one (./tools/start.js --port 9223).
  • Selector flakiness: use the polling pattern above; SPAs often need a wait after domcontentloaded.
  • Chrome path not found: set CODEX_CHROME_PATH or pass --chrome-path.

Pitfalls

  • ./tools/start.js defaults to killing Chrome processes (use --no-kill to avoid this).
  • Use single quotes around JS to avoid shell-escaping issues.

References

  • codex/skills/web-browser/tools/start.js
  • codex/skills/web-browser/tools/nav.js
  • codex/skills/web-browser/tools/eval.js
  • codex/skills/web-browser/tools/screenshot.js
  • codex/skills/web-browser/tools/pick.js