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 uses Brave Browser as its engine. Here's why:
| Feature | Brave | Chrome | Why it matters |
|---|---|---|---|
| Built-in ad blocker | Shields (native) | Extension needed | Pages load faster, less noise in DOM |
| Tracker blocking | Default on | Manual config | Cleaner network logs for debugging |
| Fingerprint protection | Native | None | Better privacy for automated sessions |
| Chromium-based | Full CDP support | Full CDP support | Same DevTools Protocol, same power |
| Open source | Yes (MPL 2.0) | Chromium yes, Chrome no | Transparent, auditable |
| Resource usage | Lower memory | Higher memory | Better for running alongside your work |
TL;DR: Brave = Chrome's power + built-in privacy + less bloat. Perfect for automation.
cdpilot also works with Chrome and Chromium as fallback. Brave is recommended, not required.
# 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
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 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.