TL;DR — The Smart Eye for coding agents. chrome-cdp-ex lets an agent see and act inside your real browser: logged-in tabs, page layout, visible styles, action receipts, CSS source tracing, and long-session reports.

Playwright is excellent for deterministic tests in a clean browser. chrome-cdp-ex is for live-page perception when the agent needs to understand the browser you are actually using.

Browser agents usually fail for boring reasons: they cannot tell what changed, they lose context after a click, or they can inspect DOM but not the page humans see. This tool gives them the missing perception layer.

Use chrome-cdp-ex when the page already matters and the agent needs useful context before acting.

• The user is already logged in and you do not want to recreate state.
• The agent needs to understand layout, visible styles, and interactive targets cheaply.
• You want each click, fill, reload, or upload to explain what changed.
• You need a trail: screenshots, logs, reports, checkpoints, replay, or a Playwright draft.

Use Playwright when you need a clean, repeatable browser test from scratch.

The release proof measures the agent path this tool is built for: see the page, act, verify, recover, and hand off evidence. For v2.11.0, one 10-round campaign spans matched MCP/CLI routes, Killer Path, a 5000+ node large-app fixture, and five distinct local real-app profiles.

View the benchmark proof -> · Read the v2.11.0 release notes ->

This is not a synthetic unit test. It launches disposable debug browsers, exercises perception, action evidence, recovery, CSS tracing, frame/modal/HMR probes, and report handoff, then blocks promotion claims if the gate fails. Re-run the same campaign with:

npm run benchmark:campaign -- --rounds 10 --types mcp,cli,killer,large-app,real-app,real-app,real-app,real-app,real-app,cli --real-app-targets dashboard,docs-app,auth-flow,data-table,canvas-heavy --settle-ms 0 --json --output release-campaign.json

For the shortest first run, use the Killer Path walkthrough.

1. Choose an install source.

Use the GitHub release tarball when you want a pinned v2.11.0 install:

curl -L -o pi-chrome-cdp-2.11.0.tgz https://github.com/EndeavorYen/chrome-cdp-ex/releases/download/v2.11.0/pi-chrome-cdp-2.11.0.tgz
mkdir -p chrome-cdp-ex-v2.11.0
tar -xzf pi-chrome-cdp-2.11.0.tgz -C chrome-cdp-ex-v2.11.0 --strip-components=1
cd chrome-cdp-ex-v2.11.0

The GitHub Release notes publish the final tarball checksum after package validation.

Use source when you want current main:

git clone https://github.com/EndeavorYen/chrome-cdp-ex.git
cd chrome-cdp-ex

This project does not publish to the npm registry. GitHub Releases, GitHub Pages, release tags, and release assets are the official publish surfaces.

2. Load the plugin or install the skill.

# Option A: load in Claude Code for the current project/session
claude --plugin-dir .

# Option B: install globally for all projects
mkdir -p ~/.claude/skills
cp -r skills/chrome-cdp-ex ~/.claude/skills/

# Option C: install as a Codex skill
mkdir -p ~/.codex/skills
cp -r skills/chrome-cdp-ex ~/.codex/skills/

3. Run the onboarding check.

node skills/chrome-cdp-ex/scripts/cdp.mjs doctor

doctor tells you whether the browser is reachable, what to run next, and how to recover common setup issues. If CDP is not ready, use one of these paths:

• Existing browser session (preferred): open chrome://inspect/#remote-debugging (or edge://inspect) and toggle remote debugging on. Cleanest path; touches no profile state.
• Isolated debug profile: node skills/chrome-cdp-ex/scripts/cdp.mjs spawn-debug-browser edge --port 9222 --url https://example.com. Add --headless --no-sandbox for Linux CI, containers, or remote shells without a display.
• Electron app: start it with --remote-debugging-port=<port> and run with CDP_PORT=<port>.

4. Follow the golden path.

node skills/chrome-cdp-ex/scripts/cdp.mjs doctor
node skills/chrome-cdp-ex/scripts/cdp.mjs list
node skills/chrome-cdp-ex/scripts/cdp.mjs open https://example.com   # only if list is empty; add --format json for scripts
node skills/chrome-cdp-ex/scripts/cdp.mjs use <target> --name app     # optional: reuse the tab as "app" or "current"
node skills/chrome-cdp-ex/scripts/cdp.mjs perceive <target> -C -d 8
node skills/chrome-cdp-ex/scripts/cdp.mjs click <target> @ref        # or fill <target> <selector> <text>
node skills/chrome-cdp-ex/scripts/cdp.mjs verify-click <target> @ref --expect-text "Saved"
node skills/chrome-cdp-ex/scripts/cdp.mjs perceive <target> --since-action
node skills/chrome-cdp-ex/scripts/cdp.mjs report <target>            # add --format json for agent handoff; --last N / --all controls timeline size

The important bit is the loop: first perceive the page, then act, then ask what changed because of that action. Use --format json when another agent or script needs structured handoff data; action JSON includes receipt.schema = chrome-cdp-ex.action-receipt.v1.

Requires: Node.js 22+ (uses built-in WebSocket). Auto-detects Chrome, Chromium, Brave, Edge, and Vivaldi on macOS, Linux (including Flatpak), and Windows.

• Killer Path walkthrough — fastest way to dogfood the tool.
• Product strategy — why this is an agent perception layer, not another Playwright.
• Technical reference — command map, action evidence, semantic assertions, MCP server, Electron, WSL2, and benchmark gates.
• Full skill reference — every command, flag, and troubleshooting path.
• Self-improvement loop — the issue -> test -> PR -> review -> merge loop used for repeated live testing.
• Benchmark proof — how promotion claims are gated.
• v2.11.0 release notes — release notes, checksum, and package tarball asset.

chrome-cdp-ex connects to Chrome DevTools Protocol and keeps one lightweight daemon per tab. The daemon preserves session context, collects console/network/navigation evidence, and lets commands return useful next steps instead of a bare success string.

Most readers only need this loop:

doctor -> list -> open -> perceive -> click/fill -> perceive --since-action -> report

See docs/reference.md for Electron, WSL2, screenshots, CSS tracing, network mocks, checkpoints, replay, export, MCP stdio use, and all 81 commands.

Full command details are in docs/reference.md and skills/chrome-cdp-ex/SKILL.md.

Use the live benchmark before making performance or adoption claims. View the visual benchmark proof, then regenerate the raw numbers when command behavior changes.

Local run on 2026-07-10 against 5 safe local real-app fixtures: dashboard, docs-app, auth-flow, data-table, canvas-heavy. The 10-round release campaign also covered matched MCP/CLI, Killer Path, and large-app stress. Timing starts after CDP is reachable; publish competitor deltas only from measured baselines.

Regenerate this table after meaningful command, perception, or benchmark changes:

npm run benchmark:killer
npm run benchmark:mcp
npm run benchmark:campaign -- --rounds 10 --types mcp,cli,killer,large-app,real-app,real-app,real-app,real-app,real-app,cli --real-app-targets dashboard,docs-app,auth-flow,data-table,canvas-heavy --settle-ms 0 --json --output release-campaign.json
npm run benchmark:update-readme -- release-campaign.json README.md --html experiment/benchmark.html --date YYYY-MM-DD
npm run benchmark:killer -- --json > benchmark.json
npm run benchmark:generic-cdp -- --out generic-cdp-raw.json
npm run benchmark:playwright -- --out playwright-raw.json
npm run benchmark:baseline -- playwright-raw.json generic-cdp-raw.json --out baselines.json
npm run benchmark:killer -- --comparison-baselines ./baselines.json

A versioned schema example is checked in at docs/benchmarks/measured-baselines.example.json. Treat it as a format fixture only; regenerate local measured baselines before publishing comparison deltas.

Do not publish README, marketplace, awesome-list, or social comparison claims unless:

• npm run benchmark:killer -- --json exits 0 and gate.passed is true.
• A 10+ round mixed campaign covers matched MCP/CLI, Killer Path, large-app stress, and all five local real-app profiles before release or high-difficulty claims.
• Total output, per-command output, first-action-evidence, and per-command latency gates pass; inspect the gate culprit before publishing speed or efficiency claims.
• Action JSON passes the Action Receipt contract gate: eventId, dispatch, settlement.state/strategy/signals, observedDeltaDetails, blockingSignals, recoveryHint, and executable nextSteps.
• Competitor comparisons use npm run benchmark:killer -- --comparison-baselines ./baselines.json with measured baselines, not the planning-only heuristic-smoke-baseline.
• docs/examples/killer-path.md still covers real browser perception, failed action recovery, CSS tracing, and export handoff.
• Workflow handoffs from record-actions --format json and export-playwright --format json distinguish exported, skipped, review-needed, and live-only steps.
• If any benchmark gate criterion fails, block promotion and fix the failed criterion before publishing the claim.

Benchmark methodology and baseline commands are in docs/reference.md#benchmark-gate.

Run these before changing command behavior or docs:

npm test
npm run lint
npm run check:docs
npm run smoke:live

• Original: pasky/chrome-cdp-skill by Petr Baudis (daemon-per-tab architecture and core CDP client)
• Contributors: ynezz (Flatpak paths), Jah-yee, Rolf Fredheim
• This fork: @ref system, perceive-first workflow, action feedback, background observation, realistic input simulation, form automation, WSL2 support, and 29 additional commands

MIT