Cdpilot

Zero-dependency browser automation from your terminal. One command, full control.

npm version npm downloads License: MIT Node.js MCP Compatible cdpilot MCP server

Quick Start

npx cdpilot launch    # Start browser with CDP
npx cdpilot go https://example.com
npx cdpilot shot      # Take screenshot

No config files. No boilerplate. Just npx and go.

Why cdpilot?

AI agents and developers need browser control that just works:

• Zero config — npx cdpilot launch starts an isolated browser session
• Zero dependency — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP
• 70+ commands — Navigate, click, type, screenshot, network, console, accessibility, video understanding, progressive anti-bot resilience, and more
• AI-agent friendly — Designed for Claude, GPT, Gemini, and any LLM tool-use workflow
• Isolated sessions — Your personal browser stays untouched. cdpilot runs in its own profile
• Visual feedback — Green glow overlay, cursor visualization, click ripples, and keystroke display keep you informed during automation
• Multi-project isolation — Each project gets its own browser instance and port automatically, no conflicts
• AI control warning — Red toast notification appears when you hover during active automation
• Privacy-first — Everything runs locally. No data leaves your machine

Browser Selection (Workload-Aware Auto-Pick)

cdpilot picks the right browser for what you're doing. auto (default) is a two-axis policy — extension workload × platform stability:

Your workload	Auto-pick order
Has extensions registered (ext-install)	vivaldi → brave → edge → chromium → chrome
No extensions (pure automation)	chrome → vivaldi → edge → chromium → brave

Override anytime:

cdpilot browser            # show current pick + reason
cdpilot browser vivaldi    # pin to Vivaldi
cdpilot browser auto       # restore smart default

Why the split?

• Chrome 147+ silently drops --load-extension for unpacked extensions (no error, no warning). Verified — chrome://extensions shows 0 items.
• Vivaldi, Brave, Edge, Chromium honor --load-extension (tested).
• On macOS 26 (Tahoe) Brave 1.89 crashes deterministically at ~7min uptime (SIGTRAP in ThreadPoolForegroundWorker). cdpilot detects the OS and demotes Brave automatically until a fixed Brave release ships.

Each browser gets its own isolated profile (~/.cdpilot/.../profile-vivaldi etc.) so switching never causes prefs corruption.

Installation

# Use directly (no install needed)
npx cdpilot <command>

# Or install globally
npm i -g cdpilot

Requirements: Node.js 18+ and one of: Brave Browser, Google Chrome, or Chromium.

First-time setup

npx cdpilot setup     # Auto-detect browser, create isolated profile
npx cdpilot launch    # Start browser with CDP enabled
npx cdpilot status    # Check connection

Upgrading from 0.4.x → 0.5.0 — read this first

One breaking change, the rest is additive.

Breaking — Visual feedback default flipped to OFF. The green glow border, animated fake cursor, click ripples, and keystroke display made cdpilot feel like an amateur typing on every page. They are now opt-in:

cdpilot show on     # restore the old visual feedback layer
cdpilot show off    # default since 0.5.0

The MCP server's persistent-glow flow (CDPILOT_MCP_SESSION=1) is unchanged — AI agents that rely on visible feedback during a session still see it automatically. Only direct-CLI users see the difference.

New in 0.5.0 (no migration needed):

• cdpilot dismiss — heuristic auto-click for "Stay signed out / No thanks" buttons on LLM chat sign-up walls.
• cdpilot adaptive on — auto-escalate to stealth on CAPTCHA-protected hosts, with persistent per-host memory.
• cdpilot cookies save/load — export/import cookies as JSON to replay CF/DataDome clearance across runs.
• cdpilot context create/list/close + CDPILOT_TARGET — isolated browser contexts for true parallel automation inside a single browser.
• cdpilot fast / cdpilot show — bundled timing + visual toggles.
• Pure performance: post-load sleep 1500ms → 300ms, scrollIntoView instant, WebSocket connection pool, /json TTL cache.

See CHANGELOG.md for the full list with rationale.

Commands

Navigation & Content

cdpilot go <url>              # Navigate to URL
cdpilot content               # Get page text content
cdpilot html                  # Get page HTML
cdpilot shot [file]           # Take screenshot (PNG)
cdpilot pdf [file]            # Save page as PDF

Interaction

cdpilot click <selector>      # Click element
cdpilot type <selector> <text># Type into input
cdpilot fill <selector> <val> # Set input value (React-compatible)
cdpilot submit <form>         # Submit form
cdpilot hover <selector>      # Hover element
cdpilot keys <combo>          # Keyboard shortcut (ctrl+a, enter, etc.)
cdpilot scroll-to <selector>  # Scroll element into view
cdpilot drag <from> <to>      # Drag and drop

Debugging

cdpilot console [url]         # Capture console logs
cdpilot network [url]         # Monitor network requests
cdpilot debug [url]           # Full diagnostic (console+network+perf+shot)
cdpilot perf                  # Performance metrics
cdpilot eval <js>             # Execute JavaScript
cdpilot eval-batch <json>     # Run N JS expressions in 1 roundtrip (5-30x faster)

# Example: read 4 DOM values in a single CDP roundtrip instead of 4
cdpilot eval-batch '["document.title","location.href","document.links.length","document.images.length"]'
# → [{"ok":true,"value":"..."}, {"ok":true,"value":"..."}, ...]

Performance

cdpilot block                                # Show status
cdpilot block on                             # Enable (default preset: images+fonts+ads)
cdpilot block off                            # Disable
cdpilot block preset images,fonts,ads,media  # Set patterns from named presets
cdpilot block patterns '*.png' '*.woff2'     # Custom URL patterns
cdpilot block clear                          # Drop all patterns

Stealth caveat: block changes the fingerprint surface — real browsers fetch images, fonts, and analytics. Cloudflare-class bot detectors notice missing requests. Keep block off for stealth/anti-bot targets; turn it on for known-safe internal sites where speed matters more than blending in.

cdpilot fast                       # Show status (effective auto-wait ms)
cdpilot fast on                    # Auto-wait 5s → 2s, less idle padding
cdpilot fast off                   # Back to defaults
CDPILOT_WAIT_MS=1000 cdpilot click # Per-command override (env wins over fast mode)

cdpilot show                       # Show status (visual feedback on/off)
cdpilot show on                    # Re-enable glow border + cursor + ripples + keystrokes
cdpilot show off                   # Default since 0.4.4 — quiet, professional output

Visual feedback default changed in 0.4.4 — the old animations (green glow, moving cursor, click ripples) used to make every action look like an amateur driving the screen. They're now opt-in via cdpilot show on. The MCP server's persistent-glow flow (CDPILOT_MCP_SESSION=1) is unaffected — AI agents that rely on visible feedback during a session still see it automatically.

Tab Management

cdpilot tabs                  # List open tabs
cdpilot new-tab [url]         # Open new tab
cdpilot switch-tab <id>       # Switch to tab
cdpilot close-tab [id]        # Close tab
cdpilot close                 # Close active tab

Network Control

cdpilot throttle slow3g       # Simulate slow 3G
cdpilot throttle fast3g       # Simulate fast 3G
cdpilot throttle offline      # Go offline
cdpilot throttle off          # Back to normal
cdpilot proxy <url>           # Set proxy (legacy single-URL form)
cdpilot proxy off             # Remove proxy

# v0.7.0: named pools (BrightData, IPRoyal, Anchor, etc.)
cdpilot proxy add brd "http://USER:[email protected]:22225" --geo us
cdpilot proxy add ipr "http://USER:[email protected]:12321" --sticky
cdpilot proxy use brd         # Activate one pool
cdpilot proxy list            # Show pools (credentials redacted)
cdpilot proxy show [<name>]   # Active or named pool URL (redacted)
cdpilot proxy remove <name>   # Drop a pool

TLS Fingerprint (v0.8.0)

cdpilot tls-check                        # Probe JA3/JA4/H2 via tls.peet.ws
cdpilot tls-check --service browserleaks # Alternate echo
cdpilot tls-check --json                 # Raw JSON

Known limitation: v0.8.0 ships the probe (tls-check) but no in-tree TLS fix. There is no Chromium-based TLS-corrected browser that ships as a standalone binary exposing --remote-debugging-port. Camoufox is Firefox+Juggler (no CDP); Patchright / undetected-chromedriver / nodriver are Python/Playwright libraries, not standalone browsers. cdpilot's CDP-only architecture is incompatible with all of them without a protocol adapter. Tracking: v0.9 roadmap (TLS-MITM plugin using curl-impersonate semantics, OR BoringSSL-patched Chromium fork).

Request Interception

cdpilot intercept block <pattern>                    # Block requests
cdpilot intercept mock <pattern> <json-file>         # Mock responses
cdpilot intercept headers <pattern> <header:value>   # Add headers
cdpilot intercept list                               # List active rules
cdpilot intercept clear                              # Clear all rules

Device Emulation

cdpilot emulate iphone        # iPhone emulation
cdpilot emulate ipad          # iPad emulation
cdpilot emulate android       # Android emulation
cdpilot emulate reset         # Back to desktop

Geolocation

cdpilot geo istanbul          # Set location to Istanbul
cdpilot geo london            # Set location to London
cdpilot geo 41.01 28.97       # Custom coordinates
cdpilot geo off               # Remove override

Accessibility

cdpilot a11y                  # Full accessibility tree
cdpilot a11y summary          # Quick summary
cdpilot a11y find <role>      # Find elements by ARIA role

Session Management

cdpilot session               # Current session info
cdpilot sessions              # List all sessions
cdpilot session-close [id]    # Close session

Advanced

cdpilot cookies [domain]             # List cookies (filter by domain)
cdpilot cookies save <file> [<domain>]  # Export cookies as JSON
cdpilot cookies load <file>          # Import cookies (replay CF clearance)
cdpilot cookies save --host x.com    # Save to per-host cache
cdpilot cookies load --host x.com    # Load from per-host cache
cdpilot cookies list                 # Cached hosts + age + CF clearance flag
cdpilot cookies clear --host x.com   # Remove one host
cdpilot cookies clear --all          # Wipe entire cache
cdpilot cookies clear --older-than 7d  # Remove stale entries
cdpilot cookies auto on              # Toggle global auto-save/replay flag (v0.6.1: requires safe-list)
cdpilot cookies auto add <host>      # Opt host into auto save/replay (v0.6.1)
cdpilot cookies auto remove <host>   # Remove host from safe-list
cdpilot cookies auto list            # Enable flag + current safe-list
cdpilot cookies cf-replay <url>      # Inject cached CF clearance before nav
cdpilot wipe [--cookies|--storage|--tabs|--keep h1,h2]
                                     # v0.6.2: per-task state hygiene (cross-task contamination)
cdpilot storage               # localStorage contents
cdpilot upload <sel> <file>   # Upload file to input
cdpilot multi-eval <js>       # Execute JS in all tabs
cdpilot headless [on|off]     # Toggle headless mode
cdpilot frame list            # List iframes
cdpilot dialog auto-accept    # Auto-accept dialogs
cdpilot permission grant geo  # Grant geolocation

Parallel Contexts

cdpilot context create [url]  # Make fresh browser context + tab (prints JSON)
cdpilot context list          # Tree of contexts and their tabs
cdpilot context close <ctx>   # Destroy a context (refuses 'default')

Address a specific context's tab in subsequent commands via the env pin:

ID=$(cdpilot context create https://example.com | jq -r .target_id)
CDPILOT_TARGET=$ID cdpilot eval 'document.title'

True isolation — each context has its own cookie/storage jar. Designed for running N AI chat queries in parallel without history pollution, or A/B testing logged-in vs logged-out flows without spinning up multiple browsers.

Smart Navigation (LLM-aware)

cdpilot dismiss               # Click best "Stay signed out / No thanks" button
cdpilot dismiss aggressive    # Handle chained modals (cookie banner → signup)

Built-in English + Turkish pattern library. Explicitly excludes destructive lookalikes (Delete account, Sign out, Subscribe) — safe to chain into a query workflow.

Video Understanding

A single screenshot can't see motion. cdpilot watch runs a continuous screencast (Page.startScreencast) into a ring buffer of JPEG frames, so an AI agent can query a time window and actually watch what happened — animations, mouse cursor movement, scroll, an explosion effect — instead of guessing from one still frame.

cdpilot watch start <url|file://...>   # Begin screencast, play the video
cdpilot watch query --at 1:23 --window 5s  # Frames around a timestamp
cdpilot watch ask "did the menu animate open?"  # Ask about recent frames
cdpilot watch status          # Show capture state + buffer size
cdpilot watch stop            # Stop the screencast

Works on both local files (file://...) and online video (YouTube, Vimeo, Twitter, Facebook, Instagram). Zero dependency — Pillow is optional and only used for motion-detection between frames.

DRM limitation: DRM-protected players (Netflix and similar) render as black frames at the CDP layer — cdpilot cannot capture them. Everything non-DRM works.

MCP exposes this as browser_watch_* tools for AI agents.

Video Understanding (commands)

cdpilot watch start <url|file://>     # Start screencast, play video
cdpilot watch query --at 1:23 --window 5s  # Frames around a timestamp
cdpilot watch ask "did the modal slide in?"  # Ask about recent frames
cdpilot watch status                   # Capture state + buffer size
cdpilot watch stop                     # Stop screencast

Stealth & CAPTCHA

Zero-dependency anti-fingerprint layer — patches navigator.webdriver, chrome.runtime, plugins (proper PluginArray inheritance), WebGL vendor/renderer, permissions, hardware concurrency, and the Worker constructor. Injected via Page.addScriptToEvaluateOnNewDocument before any page script runs. Disabled by default; opt-in.

At launch, cdpilot also passes --disable-blink-features=AutomationControlled, which closes the Blink runtime flag that Cloudflare and DataDome probe to detect an automated browser.

Three-tier stealth mode

cdpilot mode is the recommended entry point — one switch that sets how much fingerprint surface cdpilot touches, lightest to heaviest:

cdpilot mode             # show current tier + what it injects
cdpilot mode regular     # no fingerprint patch — cleanest, fastest (default)
cdpilot mode stealth     # light patch: webdriver / chrome.runtime / permissions
cdpilot mode undetected  # full patch: + plugin array + WebGL + Worker

regular is the default because Stealth Bench V1 found the full patch set alone lowered scores — a synthetic plugin array is itself a tell. The stealth tier deliberately omits plugin spoofing; escalate to undetected only for hard targets. The adaptive layer learns the right tier per host and escalates on CAPTCHA. Effect applies on the next navigation. Env override: CDPILOT_MODE=<tier>. The legacy stealth on/off toggle still works and stays coherent with the tier:

cdpilot stealth on            # enable fingerprint patches (opt-in)
cdpilot stealth off           # disable (default)
cdpilot stealth status        # show which patches are applied

cdpilot captcha-check         # JSON detection of Turnstile/hCaptcha/reCAPTCHA/
                              # DataDome/PerimeterX/Arkose/GeeTest. Exit 0/3
cdpilot captcha-wait [sec]    # block until user solves (interactive)
                              # or poll with JSON stream (non-interactive)

cdpilot adaptive [on|off|status]
                              # Auto-escalate to stealth on hosts that show
                              # CAPTCHA. Persistent per-host memory.
cdpilot adaptive forget <host>
                              # Remove a hostname from the stealth list
cdpilot adaptive clear        # Drop the stealth host memory entirely

Adaptive mode is the "run fast, climb walls when seen" automation: cdpilot runs in the open lane by default, detects CAPTCHA after each navigation, and when it sees one — adds the host to a persistent list, retries once with stealth on. Never auto-demotes. Conservative by design.

Friction Ladder (progressive anti-bot detection)

Real sites don't just throw a CAPTCHA — they stack defenses incrementally. cdpilot friction reports which rung is currently active so an agent can react appropriately instead of guessing. Six levels, lowest to highest:

none → rate_limited → soft_captcha → login_wall → otp_sms → hard_block

cdpilot friction              # JSON: current rung + recommended response policy

Bilingual (English + Turkish) DOM heuristics. The detection is read-only — it never bypasses anything. The response policy is deliberately conservative:

• rate_limited → automatic exponential backoff + retry
• soft_captcha → defer to the captcha tools
• login_wall / otp_sms / hard_block → flagged for human handoff, not autonomously solved

That last line is an ethics boundary, not a missing feature: cdpilot will not attempt to defeat a login, an OTP/SMS gate, or an outright block on its own. MCP exposes this as browser_friction.

Press-and-Hold (PerimeterX / HUMAN behavioral challenge)

PerimeterX's "Press & Hold" is a behavioral challenge, not a token — there's no provider to call. The only solution is a real press → hold → release gesture, which cdpilot emits via the CDP Input domain: a Gaussian-randomized ~3–7s hold with ±1–2px micro-jitter while the button is held.

cdpilot press-hold                       # auto-find the px-captcha target
cdpilot press-hold "#px-captcha button"  # explicit selector

captcha-solve auto-routes here when it detects a perimeterx challenge. MCP exposes this as browser_press_hold.

Captcha Solver Plugins (v0.6+)

Optional integration with 2captcha, anti-captcha, and capmonster. Per-solve cost ~$0.001–0.003. API keys stored in ~/.cdpilot/captcha-providers.json (chmod 600) — never committed to git.

# One-time setup
cdpilot captcha config --provider 2captcha --api-key YOUR_KEY
cdpilot captcha config --provider anticaptcha --api-key YOUR_KEY  # fallback

# Enable auto-solve (adaptive layer auto-solves on detect)
cdpilot captcha auto on

# Manual solve (debug / scripting)
cdpilot captcha solve --type recaptcha-v2 --site-key SK --url https://example.com
# returns: {"token": "03AGdBq2...", "duration_ms": 12500, "cost": 0.003, "provider": "2captcha"}

cdpilot captcha solve --type hcaptcha --site-key SK --url URL
cdpilot captcha solve --type turnstile --site-key SK --url URL
cdpilot captcha solve --type funcaptcha --site-key SK --url URL

# Status & balance
cdpilot captcha status   # {"configured": [...], "preferred": "2captcha", "auto_enabled": true}
cdpilot captcha balance  # {"2captcha": 1.23, "anticaptcha": 0.50}

Supported types: recaptcha-v2, recaptcha-v3, hcaptcha, turnstile, funcaptcha

Tokens are injected via Runtime.evaluate CDP — no browser-side libraries required. When captcha auto on is set, the adaptive layer detects and solves automatically after each navigation. Without auto-on, detection still works but solving is manual.

Expected bench improvement (v0.6): reCaptcha 2/6 → 5+/6, hCaptcha 2/3 → 3/3

Image CAPTCHA + profile warming

captcha-solve handles the image-based rate-limit CAPTCHAs that the token solvers above don't cover:

cdpilot captcha-solve                       # auto-detect + route (incl. press-hold)
cdpilot captcha-solve --provider amazon-local  # offline OCR (default)
cdpilot captcha-solve --provider capsolver   # BYOK image-to-text
cdpilot captcha-solve --provider 2captcha    # BYOK image-to-text

• Amazon classic image CAPTCHA (the "Type the characters you see" page) is OCR'd offline via the optional amazoncaptcha library (pip install amazoncaptcha — pure-Python + Pillow, MIT). Not installed = the command reports it and exits cleanly; no hard dependency added.
• BYOK providers (capsolver, 2captcha) use their image-to-text APIs via CAPSOLVER_API_KEY / TWOCAPTCHA_API_KEY.

cdpilot profile warm          # age the profile for reCAPTCHA v3 score

profile warm browses a set of low-risk sites to build cookie/history age, which nudges reCAPTCHA v3's behavioral score upward over time. Slow by design — run it ahead of a session, not inline.

Verified against public bot-detection panels:

• bot.sannysoft.com: 24/24 PASS (WebDriver, Chrome obj, Plugins as PluginArray, WebGL, PHANTOM_*, HEADCHR_*, SELENIUM_DRIVER)
• bot.incolumitas.com intoli: 6/6 OK — new-tests: 6/7 OK (one FAIL = pure CDP presence, cannot be JS-patched)
• nowsecure.nl (Cloudflare full challenge): passed
• arh.antoinevastel.com/areyouheadless: "You are not Chrome headless"

Reliability

cdpilot browser [name|auto]   # workload-aware browser selection
cdpilot health                # JSON: alive, port, tabs, browser, today's crashes

cdpilot health is designed for shell watchdogs:

until cdpilot health >/dev/null; do cdpilot launch; sleep 2; done

Surfaces today's Brave crash count from ~/Library/Logs/DiagnosticReports/ on macOS — spot degradation before your automation silently stalls.

Scaling & Workstation Use

CDPILOT_POOL_SIZE=4 cdpilot launch   # 4 separate browser processes
CDPILOT_OFFSCREEN=1 cdpilot launch   # headed, but no window on your screen

• Multi-instance pool (CDPILOT_POOL_SIZE=N) starts N independent browser processes and dispatches work to the least-loaded one, for N × per-instance parallelism. Default is 1 — single instance, no change for existing users.
• Off-screen mode (CDPILOT_OFFSCREEN=1) keeps the browser headed (real rendering, no headless fingerprint) but positions the window where it can't steal focus — meant for automating on a workstation you're also using.
• Docker + Xvfb harness (cdpilot-bench/docker/) runs headed-in-Xvfb so bench/automation runs never pop a window on the host display. CI-ready. Note that software rendering (no GPU) lowers anti-bot scores versus native — it's an isolated environment for reproducibility, not the headline configuration.

Use with AI Agents

cdpilot is designed to be called by AI agents as a tool:

Claude Code (MCP)

{
  "mcpServers": {
    "cdpilot": {
      "command": "npx",
      "args": ["cdpilot", "mcp"]
    }
  }
}

Any LLM (tool-use)

{
  "name": "browser",
  "description": "Control a browser via CDP",
  "parameters": {
    "command": "go https://example.com"
  }
}

Python (subprocess)

import subprocess
result = subprocess.run(["npx", "cdpilot", "go", url], capture_output=True, text=True)
print(result.stdout)

Environment Variables

Variable	Default	Description
CDP_PORT	9222	CDP debugging port
CHROME_BIN	Auto-detect	Browser binary path
CDPILOT_PROFILE	~/.cdpilot/profile	Isolated browser profile
BROWSER_SESSION	Auto	Session identifier
CDPILOT_MODE	regular	Stealth tier override (regular/stealth/undetected)
CDPILOT_OFFSCREEN	0	Headed but render off-screen — no window steals focus
CDPILOT_POOL_SIZE	1	N separate browser processes, least-loaded dispatch

How It Works

┌─────────────┐     HTTP/WebSocket      ┌──────────────┐
│  cdpilot │ ◄──────────────────────► │ Brave/Chrome │
│   (CLI)     │    Chrome DevTools       │  (CDP mode)  │
└─────────────┘     Protocol             └──────────────┘
       │                                        │
       │  Zero dependencies                     │  Isolated profile
       │  Pure HTTP + WebSocket                 │  Separate from your
       │  ~2500 lines, single file              │  personal browser
       └────────────────────────────────────────┘

No Puppeteer. No Playwright. No Selenium. Just direct CDP communication.

Stealth Bench V1

cdpilot is benchmarked against a suite of 80 high-friction web tasks to measure success rates against modern anti-bot systems. Gemini 2.5 Flash drives cdpilot as the controller; success is defined as full task completion without interception.

v0.5.3 Results (current)

Category	Success / Total	Rate
Custom Antibot	5 / 5	100.0%
Temu Slider	1 / 1	100.0%
hCaptcha	2 / 3	67.0%
Cloudflare	12 / 22	55.0%
DataDome	5 / 13	38.0%
reCaptcha	2 / 6	33.0%
Akamai	1 / 6	17.0%
PerimeterX	2 / 18	11.0%
GeeTest	0 / 4	0.0%
Shape	0 / 1	0.0%
Kasada	0 / 1	0.0%
Total	30 / 80	37.5%

Version history

Version	Mode	Total	Rate
v0.5.0	Baseline (stealth off / adaptive off)	30 / 80	37.5%
v0.5.0	Stealth only (stealth on / adaptive off)	32 / 80	40.0%
v0.5.0	Full (stealth on / adaptive on)	26 / 80	32.5%
v0.5.1	Full — regression fix	29 / 80	36.25%
v0.5.2	Full — entropy auto-hook	28 / 80	35.0%
v0.5.3	Full — entropy scope tightened	30 / 80	37.5%
v0.6.0	+ captcha solver + cookies-auto (regression)	15 / 80	18.75%
v0.8.0	Full — cookies safe-host scoped + per-task wipe (no proxy, no TLS fork)	29 / 80	36.25%
v0.7.0 (slot)	+ named proxy pools	depends on user proxy	—
v0.8.0 (slot)	+ TLS-aware launcher (camoufox/undetected-chrome)	depends on browser choice	—

What cdpilot does not do: cdpilot is an avoidance engine, not a CAPTCHA solver. We prioritize structural stealth (JS fingerprinting, behavioral entropy) to prevent challenges from appearing. When a CAPTCHA blocks progress and cannot be bypassed, the task fails — that is the honest definition of our success rate. PerimeterX (2/18), GeeTest (0/4) and Akamai (1/6) are known weaknesses; v0.7+ (residential proxy) and v0.8+ (TLS fingerprint correction via camoufox) target these directly.

Recommended Configuration

Based on Stealth Bench V1 results:

• Speed-first (most use cases): cdpilot launch — default browser behavior, no patches
• Stealth-on (RECOMMENDED, best overall): cdpilot launch && cdpilot stealth on
• Full adaptive (specific captcha-heavy workflows): cdpilot launch && cdpilot stealth on && cdpilot adaptive on

The full adaptive layer is bench-neutral vs baseline (30/80 vs 30/80) for Stealth Bench V1's task mix. Stealth-only (32/80 = 40%) is still the best-performing single variant. For your specific workload, profile both and pick.

Comparison

Feature	cdpilot	Puppeteer	Playwright	Selenium
Install size	~50KB	400MB+	200MB+	100MB+
Dependencies	0	50+	30+	Java + drivers
Setup time	instant	minutes	minutes	painful
AI-agent ready	yes	manual	manual	manual
Browser download	no	yes (Chromium)	yes (3 browsers)	no
CLI-first	yes	no (library)	no (library)	no
MCP support	yes	no	no	no

Monetization / Pro (Coming Soon)

cdpilot CLI is and will always be free and open source (MIT).

Future paid offerings:

• cdpilot cloud — Remote browser instances, no local browser needed
• Team dashboard — Shared sessions, audit logs, usage analytics
• Priority support — Direct help for enterprise integrations

Security

• Isolated browser profile — cdpilot runs in ~/.cdpilot/profile, separate from your daily browser. Your cookies, passwords, and history are never exposed.
• No arbitrary file access — MCP screenshot filenames are sanitized and restricted to the screenshots directory. Path traversal is blocked.
• Safe CSS selectors — All selectors passed to querySelector are JSON-escaped to prevent injection.
• No network exposure — CDP listens on 127.0.0.1 only. Remote connections are not possible by default.
• No dependencies — Zero npm/Python runtime dependencies means zero supply-chain attack surface.

Found a vulnerability? Please email the maintainer directly instead of opening a public issue.

Cookie Persistence (v0.6+)

Per-host cookie cache with auto-replay before navigation. Particularly useful for sites with expensive challenges (Cloudflare, DataDome) — once passed, clearance cookies (cf_clearance, __cf_bm) are cached and replayed on next visit.

# Enable auto-mode — cookies saved/replayed on every navigate
cdpilot cookies auto on

# Manual per-host workflow
cdpilot cookies save --host x.com   # cache current session cookies
cdpilot cookies load --host x.com   # inject before navigating
cdpilot cookies cf-replay https://x.com  # explicit CF clearance injection

# Inspect and clean
cdpilot cookies list                     # all cached hosts + age + CF flag
cdpilot cookies clear --older-than 7d   # prune stale cache

Storage: ~/.cdpilot/cookies/<host>/cookies.json (chmod 600, never committed to git). Expired cookies are filtered automatically on load.

Roadmap

The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:

Shipped

• 70+ CLI commands (navigate, click, fill, screenshot, PDF, console, network, video understanding, friction ladder...)
• MCP server for AI agent integration (Claude Code, Cursor, etc.)
• 10 built-in test assertions — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff
• Accessibility tree snapshot (a11y-snapshot) — structured data with @ref references, 500x fewer tokens than screenshots
• Token-efficient screenshots — element-level crop (13x smaller), JPEG quality control, format selection
• Vision fallback (describe) — a11y + screenshot + text in one call
• Annotated screenshots — @N badge overlays on interactive elements
• Auto-wait — MutationObserver-based, 5s automatic element waiting
• wait-for-text — adaptive text-based waiting (subtree + characterData) for streaming AI responses, async toasts, and selector-less synchronization
• eval-batch — run N JS expressions in 1 CDP roundtrip (5-30x speedup vs sequential eval)
• block — request blocking via Network.setBlockedURLs with built-in presets (images/fonts/ads/media), 3-10x faster page loads on opt-in
• dismiss — heuristic auto-click for LLM chat sign-up walls (EN+TR pattern library, destructive-action guards)
• adaptive — auto-escalate to stealth on CAPTCHA-protected hosts, persistent per-host memory ("run fast, climb walls")
• cookies save/load — export/import cookies as JSON (replay CF/DataDome clearance across runs)
• context pool + CDPILOT_TARGET — isolated browser contexts for true parallel automation in a single browser (Playwright's parallel-tabs model)
• fast / show — bundled timing + visual toggles. Default quiet/fast in 0.5.0
• WebSocket pool + /json TTL cache — zero-regression connection reuse for MCP/batch workloads
• Batch commands — pipe JSON arrays via stdin for multi-step automation
• Visual feedback system (persistent green glow, cursor, ripples, keystroke display)
• AI control warning toast (red warning when user interacts during automation)
• Multi-project browser isolation (each project gets its own port + profile)
• Pre-flight wizard (auto-installs dependencies on first run)
• Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
• DevExtension system (native JS injection without browser store)
• Smart commands — smart-click, smart-fill, smart-select — interact by visible text, no CSS selectors needed, no LLM required. Now with a disabled-element guard (no more false "clicked" on disabled buttons), Shadow DOM traversal (Lightning, Polymer, lit-element widgets), locale-aware text matching (Turkish İ/i, German ß), and floating-label support for smart-fill (Material / Ant / Chakra via aria-labelledby and closest label resolution)
• Video understanding (watch) — continuous screencast into a ring buffer so an AI agent can query a time window and see motion (animation, cursor, scroll), not just one still frame. Local file:// and online video (YouTube/Vimeo/Twitter/etc.); DRM players (Netflix) excluded
• Friction ladder (friction) — 6-level progressive anti-bot detection (none → rate_limited → soft_captcha → login_wall → otp_sms → hard_block), bilingual EN+TR, read-only; rate-limit auto-backoff, login/OTP/hard-block flagged for human handoff (no autonomous bypass)
• Three-tier stealth mode (mode regular|stealth|undetected) — single switch over fingerprint surface, with per-host adaptive tier learning
• Press-and-hold solver (press-hold) — humanized press → hold → release gesture (Gaussian 3–7s + micro-jitter) for PerimeterX/HUMAN behavioral challenges; captcha-solve auto-routes here
• Image CAPTCHA + profile warming — offline Amazon image OCR (optional amazoncaptcha lib) + BYOK image-to-text (capsolver/2captcha); profile warm ages the profile for reCAPTCHA v3 score
• Multi-instance pool + off-screen mode (CDPILOT_POOL_SIZE, CDPILOT_OFFSCREEN) — N parallel browser processes; headed rendering without stealing window focus
• Data extraction (extract) — structured DOM data in text, JSON, or list format
• Page observation (observe) — list all interactive elements with available actions
• Script runner (run) — execute .cdp script files with pass/fail reporting

Coming Soon

• iframe support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
• Session recording & replay — record browser sessions and replay them deterministically
• Stealth mode (Pro) — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
• cdpilot Cloud — hosted browser sessions API, REST + WebSocket MCP endpoint
• Chrome Extension — use cdpilot from any browser without CLI
• Performance audit — Core Web Vitals (LCP, CLS, INP) via CDP Performance domain
• WCAG accessibility audit — automated a11y compliance reporting
• Claude Code Skill mode — run as a .claude/skills/ skill in addition to MCP

Have an idea? Open an issue or submit a PR!

Contributing

git clone https://github.com/mehmetnadir/cdpilot.git
cd cdpilot
npm install
npm test

PRs welcome! Please read CONTRIBUTING.md first.

License

MIT — do whatever you want.

---

Built with the cdpilot mindset: one tool, one job, done right.