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
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 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
cdpilot proxy off # Remove proxy
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
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
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)
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.
| 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.
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 callsmart-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 91 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.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
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.