Zero-dependency browser automation CLI. Raw CDP, 60+ commands, stealth + adaptive escalation, CAPTCHA solvers, proxy pools, TLS probe, MCP server. No Puppeteer/Playwright/Selenium.
Zero-dependency browser automation from your terminal. One command, full control.
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.
AI agents and developers need browser control that just works:
npx cdpilot launch starts an isolated browser sessioncdpilot 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?
--load-extension for unpacked extensions
(no error, no warning). Verified — chrome://extensions shows 0 items.--load-extension (tested).Each browser gets its own isolated profile (~/.cdpilot/.../profile-vivaldi
etc.) so switching never causes prefs corruption.
# 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.
npx cdpilot setup # Auto-detect browser, create isolated profile
npx cdpilot launch # Start browser with CDP enabled
npx cdpilot status # Check connection
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.scrollIntoView instant,
WebSocket connection pool, /json TTL cache.See CHANGELOG.md for the full list with rationale.
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
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
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":"..."}, ...]
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:
blockchanges the fingerprint surface — real browsers fetch images, fonts, and analytics. Cloudflare-class bot detectors notice missing requests. Keepblockoff 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.
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
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:PASS@brd.superproxy.io:22225" --geo us
cdpilot proxy add ipr "http://USER:PASS@geo.iproyal.com: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
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).
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
cdpilot emulate iphone # iPhone emulation
cdpilot emulate ipad # iPad emulation
cdpilot emulate android # Android emulation
cdpilot emulate reset # Back to desktop
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
cdpilot a11y # Full accessibility tree
cdpilot a11y summary # Quick summary
cdpilot a11y find <role> # Find elements by ARIA role
cdpilot session # Current session info
cdpilot sessions # List all sessions
cdpilot session-close [id] # Close session
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
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.
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.
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.
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.
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
Verified against public bot-detection panels:
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.
cdpilot is designed to be called by AI agents as a tool:
{
"mcpServers": {
"cdpilot": {
"command": "npx",
"args": ["cdpilot", "mcp"]
}
}
}
{
"name": "browser",
"description": "Control a browser via CDP",
"parameters": {
"command": "go https://example.com"
}
}
import subprocess
result = subprocess.run(["npx", "cdpilot", "go", url], capture_output=True, text=True)
print(result.stdout)
| 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 |
┌─────────────┐ 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.
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.
| 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 | 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.
Based on Stealth Bench V1 results:
cdpilot launch — default browser behavior, no patchescdpilot launch && cdpilot stealth oncdpilot launch && cdpilot stealth on && cdpilot adaptive onThe 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.
| 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 |
cdpilot CLI is and will always be free and open source (MIT).
Future paid offerings:
~/.cdpilot/profile, separate from your daily browser. Your cookies, passwords, and history are never exposed.querySelector are JSON-escaped to prevent injection.127.0.0.1 only. Remote connections are not possible by default.Found a vulnerability? Please email the maintainer directly instead of opening a public issue.
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.
The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:
a11y-snapshot) — structured data with @ref references, 500x fewer tokens than screenshotsdescribe) — a11y + screenshot + text in one callwait-for-text — adaptive text-based waiting (subtree + characterData) for streaming AI responses, async toasts, and selector-less synchronizationeval-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-indismiss — 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/json TTL cache — zero-regression connection reuse for MCP/batch workloadssmart-click, smart-fill, smart-select — interact by visible text, no CSS selectors needed, no LLM requiredextract) — structured DOM data in text, JSON, or list formatobserve) — list all interactive elements with available actionsrun) — execute .cdp script files with pass/fail reporting.claude/skills/ skill in addition to MCPHave an idea? Open an issue or submit a PR!
git clone https://github.com/mehmetnadir/cdpilot.git
cd cdpilot
npm install
npm test
PRs welcome! Please read CONTRIBUTING.md first.
MIT — do whatever you want.
Built with the cdpilot mindset: one tool, one job, done right.
FAQs
Zero-dependency browser automation CLI. Raw CDP, 70+ commands, friction ladder, 3-tier stealth, CAPTCHA + press-and-hold solvers, proxy pools, MCP server. No Puppeteer/Playwright/Selenium.
The npm package cdpilot receives a total of 93 weekly downloads. As such, cdpilot popularity was classified as not popular.
We found that cdpilot demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
An OpenCode user faced harassment after reporting a free AI usage loophole, drawing a bitter backlash in a GitHub thread that has since been deleted.
Threat Research
/Security News
319 browser extensions installed by 13.4 million users hijack searches, capture queries, and collect referral payments from Yahoo and Bing.
Threat Research
Malicious Firefox extensions mimic Phantom, Jupiter, and Bitget wallets to steal recovery phrases and private keys, with one fetching its payload remotely.