The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cdpilot listing page.
Zero-dependency browser automation from your terminal. One command, full control.
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:
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.
Requirements: Node.js 18+, Python 3.10+, and one of: Brave Browser, Google Chrome, or Chromium. (The Python websockets module is auto-installed by the pre-flight wizard on first launch.)
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:
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.
Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA
checkbox live inside <iframe>s. Name the frame chain before the element
selector with >>>, or pass --frame:
click, fill, type, submit, hover, dblclick, rightclick,
smart-click, smart-fill, smart-select and frame list|eval|shadow.name/id, or
url=<src substring>. --frame also takes a bare src substring.
>>> inside quotes or [...] is literal. A selector that matches an
element wrapping an iframe (Stripe's #card-element) enters the iframe
inside it and says so on stderr:
note: '#card-element' is not an iframe; using the iframe inside it.>>> keep working: when the part
before the first >>> finds no iframe in the page, or a segment is empty
(click "Next >>>"), the whole string is used as written, exactly as
before. If that fails too, one stderr line explains:
note: 'Home' matched no iframe; used the selector as written.
--frame never falls back: a frame it cannot find is an error (exit 1).smart-click / smart-fill / smart-select the part before the first
>>> is a frame only if it looks like a selector (it has #, . or [,
or starts with an iframe/frame tag) or is url=…; words stay text.
smart-click "Main >>> Settings" clicks the page's "Main >>> Settings"
link even when a <main> element holds an iframe. For a frame index or a
bare name use --frame.DOM.describeNode → frame id → the frame's execution context, or
Target.attachToTarget with a flat session for an out-of-process frame),
never through contentDocument, which the browser blocks cross-origin.click and smart-click are real mouse input
(isTrusted: true), like hover, dblclick, rightclick and
--entropy=on clicks; an element with no box falls back to a script click.
Mouse input is dispatched at page coordinates: each frame's offset and scale
(transform: scale(), zoom) in the page is applied automatically, so the
browser hit-tests into the right frame. Before pressing, cdpilot checks the
point (elementFromPoint in each document on the way); if something covers
the target, such as a cookie banner, it clicks the target by script instead
and says so on one stderr line (note: … is covered by div#cookie at the click point; used a script click). cdpilot's own input blocker (show on,
MCP sessions) lets only cdpilot's click through, for the click itself.smart-click / smart-fill / smart-select look in the page first and
compare texts with whitespace collapsed ( and line breaks count as
one space). An enabled page element whose text or label contains the whole
query is used. If the page's only such elements are disabled, the command
fails as before (no enabled element matches …) without looking in frames.
Otherwise the visible frames are searched breadth-first for a whole-query
match (at most 20 frames, and 2 s for all of the search's CDP calls) and the
match is reported on stderr:
smart-click: matched inside frame iframe#card (https://…). The search only
looks (no click, no typing); the command then acts once, in the chosen
frame. With no frame match, the page's partial (word) match is used as
before. When the 2 s run out:
smart-click: frame search stopped after 2s (3 of 7 frames); a frame that
had not answered by then has not been touched.smart-fill and smart-select search automatically only frames of the
page's own origin, so a typed value never lands in a third-party frame (an
ad, chat or payment widget) by accident; reach a cross-origin frame with
>>> or --frame. smart-click searches all visible frames.frame list without --frame prints the same list as before.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.
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.
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).
Address a specific context's tab in subsequent commands via the env pin:
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.
Built-in English + Turkish pattern library. Explicitly excludes destructive lookalikes (Delete account, Sign out, Subscribe) — safe to chain into a query workflow.
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.
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.
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.
cdpilot mode is the recommended entry point — one switch that sets how much
fingerprint surface cdpilot touches, lightest to heaviest:
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:
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.
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:
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 + retrysoft_captcha → defer to the captcha toolslogin_wall / otp_sms / hard_block → flagged for human handoff, not
autonomously solvedThat 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.
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.
captcha-solve auto-routes here when it detects a perimeterx challenge.
MCP exposes this as browser_press_hold.
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.
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
captcha-solve handles the image-based rate-limit CAPTCHAs that the token
solvers above don't cover:
amazoncaptcha library
(pip install amazoncaptcha — pure-Python + Pillow, MIT). Not installed = the
command reports it and exits cleanly; no hard dependency added.capsolver, 2captcha) use their image-to-text APIs via
CAPSOLVER_API_KEY / TWOCAPTCHA_API_KEY.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.
Public bot-detection panels, measured 2026-09-27, headless Brave (Chrome 154) (method and raw results):
mode | bot.sannysoft.com (31 rows) | incolumitas intoli | incolumitas fpscanner | incolumitas new-tests |
|---|---|---|---|---|
regular (no patches, default) | 28 pass / 3 fail | 5/6 | 17 ok / 3 fail / 1 warn | all ok |
stealth | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
undetected | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
'webdriver' in navigator, which is true in every modern
Chrome; faking it away would make cdpilot the odd one out.regular's fails all come from the HeadlessChrome user agent. stealth/undetected
rewrite it for the page load that go starts; a later, separate command in the same page
can still read HeadlessChrome.connectionRTT is reported as unknown in all tiers.Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4.x in April 2026; they are replaced by the table above.
cdpilot health is designed for shell watchdogs:
Surfaces today's Brave crash count from ~/Library/Logs/DiagnosticReports/
on macOS — spot degradation before your automation silently stalls.
Auto-launch. A page command (go, content, click, shot, …) that finds
the browser not running starts it the same way cdpilot launch does (same
profile, same headless/visible setting), then carries on, printing one line to
stderr: cdpilot: browser was not running — launched it (CDPILOT_NO_AUTOLAUNCH=1 to disable).
Lifecycle, status and configuration commands (launch, stop, close,
close-tab, stop-all, project-stop, session-close, status, health,
tabs, sessions, projects, headless, proxy, browser, extensions,
mcp, serve, …) never launch. CDPILOT_NO_AUTOLAUNCH=1 restores the old
"CDP connection error. Is the browser running?" error and exit code 1.
Idle auto-close. A browser that a page command auto-launched, or that the
MCP server launched (browser_launch included), closes itself after
15 minutes without a cdpilot command or a visible page change, so a
finished agent task does not leave it holding memory. An explicit CLI
cdpilot launch stays open (you may be browsing in it by hand) unless you ask:
cdpilot launch --idle-close 30 or CDPILOT_IDLE_CLOSE=30. The env var also
sets the auto-launch delay (read when the browser starts; fractions allowed);
0 turns idle close off. A browser you started yourself, or one cdpilot merely
attached to, is never closed.
What counts as use: any cdpilot command except the read-only checks (status,
health, projects, version — a cdpilot health watchdog loop does not keep
the browser alive), MCP tool calls, serve requests, a CDP client still
attached to a page (a long-running command, watch, Playwright via
connectOverCDP), and any change in the open pages' URLs or in the set of
tabs (someone navigating, a tab opened or closed). Title changes do not count,
so a page that rewrites its own title (a clock, an unread counter) cannot keep
the browser alive. cdpilot status and
cdpilot health show idle close in 12m or idle close off.
How: every command stamps ~/.cdpilot/projects/<id>/last-activity; the launch
starts a small detached watcher (one per port, no console window on Windows)
that checks every ≤30 s, stops the browser like cdpilot stop, marks it
stopped in the registry and exits — it also exits as soon as the browser is
gone for any other reason. Browsers started by serve --api are managed by the
server and have no idle close.
Timeouts. Any command takes --timeout <seconds>, before or after the
command name, or a default from CDPILOT_TIMEOUT (the flag wins; 0
disables). It bounds the whole command's wall-clock: on expiry cdpilot prints
cdpilot: timed out after <N>s (<command>) to stderr, kills the child processes
it started and exits with code 124 (like GNU timeout). A browser that was
already up and registered is left running.
For mcp and serve the value is not applied to the long-running server
itself; it is passed on to every tool call / request it runs.
Every command (and every MCP tool call) appends one JSON line to a local, per-project log, so when a browser task is done there is a record of what was done and found. Nothing leaves the machine.
Each line has ts, cmd, args, exit, duration_ms, the page url and
title after the command (when the command already had them), a ~200-char
summary of its output, the error line, and files it wrote (screenshots,
PDFs). Files live in ~/.cdpilot/projects/<project-id>/log/<YYYY-MM-DD>.jsonl.
Redaction happens before anything is written: values given to fill, type,
smart-fill, smart-select, assert-value and dialog prompt become
«redacted:N chars»; so do values of password/token/key/secret/cookie/auth
flags and headers, token-shaped arguments, and URL query/fragment values whose
names contain token, key, secret, password, auth, code or session. cookies
and storage output is never logged; eval source is, with string literals
over 40 chars cut and secret-looking ones replaced. Logging is best effort: it
never changes a command's output or exit code, and a failed write costs one
stderr line. CDPILOT_LOG=0 turns it off; CDPILOT_LOG_DAYS (default 14)
sets how many days are kept. The MCP server exposes it as browser_log.
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.CDPILOT_POOL_SIZE) — planned, not shipped yet.
See Roadmap.cdpilot-bench), not part of this package.cdpilot is designed to be called by AI agents as a tool:
| 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_TIMEOUT | unset | Default --timeout in seconds for every command (flag wins, 0 disables); expiry exits 124 |
CDPILOT_NO_AUTOLAUNCH | 0 | 1 = page commands fail with the old "Is the browser running?" error instead of launching the browser |
CDPILOT_IDLE_CLOSE | 15 | Minutes without a cdpilot command or page change before a browser cdpilot launched closes itself (fractions allowed, 0 = never; read at launch). Default applies to auto-launch and MCP launches; an explicit CLI launch is off unless this is set or --idle-close <min> is given |
CDPILOT_LOG | 1 | 0 = do not write the session log (cdpilot log) |
CDPILOT_LOG_DAYS | 14 | Days of session log to keep; older day files are deleted on the first write of a day (0 keeps all) |
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 | one Python file + a small Node launcher, no node_modules | 400MB+ | 200MB+ | 100MB+ |
| Dependencies | 0 npm (Python: websockets, auto-installed) | 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.
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:
test runner + trace viewer — cdpilot test [--watch] runs *.cdpt.js files; cdpilot trace open <run> opens a time-travel trace viewer for a runa11y-snapshot) — structured text with @ref handles the agent can act on directly, no vision model needed; 1.4–42× smaller than the page's raw HTML on the four pages we measured (2026-09-27). Not always cheaper than a screenshot: link-heavy pages produce more text than a small screenshot costsdescribe) — 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 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)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) excludedfriction) — 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)mode regular|stealth|undetected) — single switch over fingerprint surface, with per-host adaptive tier learningpress-hold) — humanized press → hold → release gesture (Gaussian 3–7s + micro-jitter) for PerimeterX/HUMAN behavioral challenges; captcha-solve auto-routes hereamazoncaptcha lib) + BYOK image-to-text (capsolver/2captcha); profile warm ages the profile for reCAPTCHA v3 scoreCDPILOT_OFFSCREEN) — headed rendering without stealing window focusextract) — structured DOM data in text, JSON, or list formatobserve) — list all interactive elements with available actionsrun) — execute .cdp script files with pass/fail reporting"iframe#card >>> input" / --frame for element commands, same-origin and cross-origin (out-of-process) frames; smart commands search frames automaticallyCDPILOT_POOL_SIZE) — N independent browser processes with least-loaded dispatch.claude/skills/ skill in addition to MCPHave an idea? Open an issue or submit a PR!
PRs welcome! Please read CONTRIBUTING.md first.
MIT — do whatever you want.
Built with the cdpilot mindset: one tool, one job, done right.