Cdpilot README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cdpilot listing page.
cdpilot
Zero-dependency browser automation from your terminal. One command, full control.
Quick Start
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 launchstarts 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:
Why the split?
- Chrome 147+ silently drops
--load-extensionfor unpacked extensions (no error, no warning). Verified —chrome://extensionsshows 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
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.)
First-time setup
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:
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,
scrollIntoViewinstant, WebSocket connection pool,/jsonTTL cache.
See CHANGELOG.md for the full list with rationale.
Commands
Navigation & Content
Interaction
Element targeting inside iframes
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:
- Works for
click,fill,type,submit,hover,dblclick,rightclick,smart-click,smart-fill,smart-selectandframe list|eval|shadow. - A frame hop is a CSS selector, a 0-based index, a
name/id, orurl=<src substring>.--framealso takes a baresrcsubstring.>>>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. - Selectors and texts that already contain
>>>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.--framenever falls back: a frame it cannot find is an error (exit 1). - For
smart-click/smart-fill/smart-selectthe part before the first>>>is a frame only if it looks like a selector (it has#,.or[, or starts with aniframe/frametag) or isurl=…; 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. - Same-origin and cross-origin frames work, including out-of-process
iframes (site isolation): cdpilot resolves each hop over CDP
(
DOM.describeNode→ frame id → the frame's execution context, orTarget.attachToTargetwith a flat session for an out-of-process frame), never throughcontentDocument, which the browser blocks cross-origin. - Inside a frame,
clickandsmart-clickare real mouse input (isTrusted: true), likehover,dblclick,rightclickand--entropy=onclicks; 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 (elementFromPointin 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-selectlook 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-fillandsmart-selectsearch 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-clicksearches all visible frames.frame listwithout--frameprints the same list as before.
Debugging
Performance
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.
Tab Management
Network Control
TLS Fingerprint (v0.8.0)
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
Device Emulation
Geolocation
Accessibility
Session Management
Advanced
Parallel Contexts
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.
Smart Navigation (LLM-aware)
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.
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)
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:
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.
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:
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 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.
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.
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:
- Amazon classic image CAPTCHA (the "Type the characters you see" page) is
OCR'd offline via the optional
amazoncaptchalibrary (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 viaCAPSOLVER_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 |
- The remaining fpscanner fail is
'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 theHeadlessChromeuser agent.stealth/undetectedrewrite it for the page load thatgostarts; a later, separate command in the same page can still readHeadlessChrome.- new-tests: every key is ok;
connectionRTTis reported as unknown in all tiers. - nowsecure.nl and areyouheadless could not be measured (a fixed always-interactive Turnstile test key; HTTP 502).
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.
Reliability
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.
Session log
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.
Scaling & Workstation Use
- 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. - Multi-instance pool (
CDPILOT_POOL_SIZE) — planned, not shipped yet. See Roadmap. - Docker + Xvfb harness — used in a separate, private benchmark
repo (
cdpilot-bench), not part of this package.
Use with AI Agents
cdpilot is designed to be called by AI agents as a tool:
Claude Code (MCP)
Any LLM (tool-use)
Python (subprocess)
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_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) |
How It Works
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 | 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 |
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
querySelectorare JSON-escaped to prevent injection. - No network exposure — CDP listens on
127.0.0.1only. 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.
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
-
testrunner +traceviewer —cdpilot test [--watch]runs*.cdpt.jsfiles;cdpilot trace open <run>opens a time-travel trace viewer for a run - Accessibility tree snapshot (
a11y-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 costs - 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 sequentialeval) -
block— request blocking viaNetwork.setBlockedURLswith 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) -
contextpool +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 +
/jsonTTL 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 forsmart-fill(Material / Ant / Chakra viaaria-labelledbyandclosestlabel 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. Localfile://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-solveauto-routes here - Image CAPTCHA + profile warming — offline Amazon image OCR (optional
amazoncaptchalib) + BYOK image-to-text (capsolver/2captcha);profile warmages the profile for reCAPTCHA v3 score - Off-screen mode (
CDPILOT_OFFSCREEN) — 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.cdpscript files with pass/fail reporting - iframe targeting —
"iframe#card >>> input"/--framefor element commands, same-origin and cross-origin (out-of-process) frames; smart commands search frames automatically
Coming Soon
- Multi-instance pool (
CDPILOT_POOL_SIZE) — N independent browser processes with least-loaded dispatch - 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
PRs welcome! Please read CONTRIBUTING.md first.
License
MIT — do whatever you want.
Built with the cdpilot mindset: one tool, one job, done right.