Are you the author? Sign in to claim
Give your AI agent eyes and hands on your real Chrome browser — your tabs, your logins, your page state. 42 commands, ze
TL;DR — Give coding agents eyes and hands on your already open Chrome / Edge / Electron session: perceive layout, act with Action Receipts, recover from overlays and stale refs, then hand off a session report.
Playwright is excellent for deterministic tests in a clean browser. chrome-cdp-ex is for live-page perception when the agent needs the browser you are actually using — cookies, login state, and open tabs included.
| Area | Change |
|---|---|
| Cross-host install | scripts/setup.mjs + INTEGRATIONS.md for Claude Code, Codex, Cursor, OpenClaw, Hermes, Pi |
| Slim skill | Always-loaded golden path; deep docs in references/ |
| MCP | Curated Tier-1 tools, allowlisted run_command, session resources |
| Release asset | Tarball includes plugin manifest, bin/chrome-cdp, and setup.mjs |
| Pain | What this gives the agent |
|---|---|
| "I can click, but I cannot really see the page." | Layout, visible text, colors, coordinates, refs, console health |
| "I clicked. Did anything happen?" | Action Receipt: dispatch, settlement, delta, blockers, next steps |
| "Which CSS rule made this button blue?" | cascade traces style back to selector and source line |
| "The bug only happens in my logged-in browser." | Real Chrome / Edge / Brave / Electron / WSL2→Windows sessions |
| "Exploration disappears after one prompt." | Reports, checkpoints, replay, Playwright export |
| Proof | Why it matters |
|---|---|
| Smart Eye benchmark | Last measured release campaign (v2.12.0, 2026-07-12): 10/10 rounds across MCP, CLI, Killer Path, large-app stress, and five real-app profiles |
| Redesign experiment | Same page, same prompt, same rounds — richer perception produced the better result |
| Killer Path | 60-second route: doctor → open → perceive → act → evidence → report |
Numbers below are from that last measured campaign. v2.14.0 shipped distribution / MCP / skill packaging; regenerate a campaign before publishing new speed or token claims.
| Use Playwright for | Use chrome-cdp-ex for |
|---|---|
| CI suites in isolated browsers | Live user sessions and authenticated tabs |
| Deterministic locators and assertions | Agent perception, diagnosis, and recovery |
| Cross-browser test matrices | Chrome / CDP / Electron inspection |
| Fresh state per test | Long-session debugging and handoff reports |
| Case | What the agent does |
|---|---|
| Logged-in dashboard inspection | doctor → list → perceive on the real dashboard |
| Action evidence after form input | fill / click return an Action Receipt (changed, no-change, failed, …) |
| CSS source tracing | cascade @ref background-color → winning selector and source line |
| Long-session debugging | status, netlog, mock / clock / throttle, report |
| Workflow capture and replay | checkpoint, record-actions, export-playwright, replay |
Measured agent path: see → act → verify → recover → hand off. The last release-quality campaign (v2.12.0) ran 10 rounds: matched MCP/CLI, Killer Path, a 5000+ node large-app fixture, and five local real-app profiles.
| Proof point | Last measured run |
|---|---|
| Release proof | v2.12.0 live campaign |
| Real-app targets | dashboard, docs-app, auth-flow, data-table, canvas-heavy |
| Campaign pass rate | 10/10 rounds |
| Quality gate | 34/34 pass in each real-app round |
| First useful observation | 2.225s avg |
| First action evidence | 2.902s avg |
| Useful observation tokens | 1,564 avg |
| Max step output | 1,113 tokens |
| Matched MCP / CLI | 100% pass; CLI used 2,481 fewer output tokens |
Benchmark page → · v2.14.0 product release →
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
Shortest first run: Killer Path. Host matrix: INTEGRATIONS.md.
Pinned release (v2.14.0):
curl -L -o pi-chrome-cdp-2.14.0.tgz https://github.com/EndeavorYen/chrome-cdp-ex/releases/download/v2.14.0/pi-chrome-cdp-2.14.0.tgz
mkdir -p chrome-cdp-ex-v2.14.0
tar -xzf pi-chrome-cdp-2.14.0.tgz -C chrome-cdp-ex-v2.14.0 --strip-components=1
cd chrome-cdp-ex-v2.14.0
Checksum is published on the GitHub Release. This project does not publish to the npm registry.
Current main:
git clone https://github.com/EndeavorYen/chrome-cdp-ex.git
cd chrome-cdp-ex
node scripts/setup.mjs --detect
node scripts/setup.mjs --for cursor --write # Cursor → .cursor/mcp.json
# Claude: claude --plugin-dir .
# Codex: mkdir -p ~/.codex/skills && cp -r skills/chrome-cdp-ex ~/.codex/skills/
# Others: node scripts/setup.mjs --for openclaw|hermes|pi|claude
node scripts/setup.mjs --verify
./bin/chrome-cdp doctor
# or: node skills/chrome-cdp-ex/scripts/cdp.mjs doctor
If CDP is not reachable:
chrome://inspect/#remote-debugging (or edge://inspect)../bin/chrome-cdp spawn-debug-browser edge --port 9222 --url https://example.com--headless --no-sandbox in CI / headless environments).--remote-debugging-port=<port> and set CDP_PORT=<port>../bin/chrome-cdp doctor
./bin/chrome-cdp list
./bin/chrome-cdp open https://example.com # if list is empty
./bin/chrome-cdp use <target> --name app # optional alias
./bin/chrome-cdp perceive app -C -d 8
./bin/chrome-cdp click app @ref # or: fill app <selector> <text>
./bin/chrome-cdp verify-click app @ref --expect-text "Saved"
./bin/chrome-cdp perceive app --since-action
./bin/chrome-cdp report app # --format json for handoffs
Loop: perceive → act → ask what changed. Action JSON uses receipt.schema = chrome-cdp-ex.action-receipt.v1.
Requires: Node.js 22+ (built-in WebSocket). Auto-detects Chrome, Chromium, Brave, Edge, and Vivaldi on macOS, Linux (including Flatpak), and Windows.
One lightweight daemon per tab keeps CDP session context, console / network / navigation buffers, and structured next steps.
doctor → list/open → perceive → click/fill → perceive --since-action → report
| Need | Start with |
|---|---|
| Understand the page | perceive, controls, summary |
| Act and verify | click, fill, press, verify-click, Action Receipt, perceive --since-action |
| UI smoke | qa |
| Reuse targets | use, current, forget |
| Debug live state | status, console, netlog, report |
| Trace styling | cascade, styles, inject |
| Preserve a session | checkpoint, record-actions, export-playwright, replay |
| Capture visuals | shot, elshot, diff-shot |
| Agent-native API | stdio MCP via mcp-server.mjs |
Full map: docs/reference.md · always-loaded skill: SKILL.md · deep flags: references/commands.md.
Use the live benchmark before publishing performance or adoption claims. Visual proof: benchmark.html.
Local run on 2026-07-12 (last measured release campaign, product label v2.12.0) against 5 safe local real-app fixtures: dashboard, docs-app, auth-flow, data-table, canvas-heavy. Timing starts after CDP is reachable. Publish competitor deltas only from measured baselines.
| Metric | Latest measured run |
|---|---|
| Total time | 10.264s avg |
| Command calls | 24 per round |
| First useful observation | 2.225s avg |
| First action evidence | 2.902s avg |
| Golden path complete | 5.353s avg |
| Estimated output tokens | 12,323 avg |
| Useful observation tokens | 1,564 avg |
| Action evidence coverage | 6 auto-evidence actions per round; no failed criteria |
| Real-app targets | dashboard, docs-app, auth-flow, data-table, canvas-heavy |
| Stale-ref recovery | covered by all real-app adversarial profiles |
| Quality gate | 34/34 pass in all 5 real-app rounds |
Regenerate this table after meaningful command, perception, or benchmark changes:
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
Schema fixture: docs/benchmarks/measured-baselines.example.json (format 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.culprit before publishing speed or efficiency claims.eventId, dispatch, settlement.state/strategy/signals, observedDeltaDetails, blockingSignals, recoveryHint, and executable nextSteps.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.record-actions --format json and export-playwright --format json distinguish exported, skipped, review-needed, and live-only steps.Methodology: docs/reference.md#benchmark-gate.
npm test
npm run lint
npm run check:docs
npm run smoke:live
@ref system, perceive-first workflow, Action Receipts, MCP adapter, cross-host setup, recovery paths, and an 81-command live-session surfaceManage multiple Claude Code agents from TUI or Web with tmux and git worktrees
Kanban-based orchestration for 10+ coding agents with isolated git worktrees per agent
⚠️ Experimentelle Skill-Sammlung für deutsches Recht (Arbeits-, Gesellschafts-, Insolvenz-, Datenschutz-, Prozessrecht u
Project management using GitHub Issues + Git worktrees for parallel agent execution