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 0 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
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.