cdpilot

Zero-dependency browser automation from your terminal. One command, full control.

<div align="center"> <img src="cdpilot-demo.gif" alt="cdpilot demo" width="600" /> </div>

Quick Start

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.

Why cdpilot?

AI agents and developers need browser control that just works:

• Zero config — npx cdpilot launch starts an isolated browser session
• Zero dependency — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP
• 40+ commands — Navigate, click, type, screenshot, network, console, accessibility, 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

Why Brave?

cdpilot 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.

Installation

# 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.

First-time setup

npx cdpilot setup     # Auto-detect browser, create isolated profile
npx cdpilot launch    # Start browser with CDP enabled
npx cdpilot status    # Check connection

Commands

Navigation & Content

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

Interaction

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

Debugging

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

Tab Management

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

Network Control

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

Request Interception

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

Device Emulation

cdpilot emulate iphone        # iPhone emulation
cdpilot emulate ipad          # iPad emulation
cdpilot emulate android       # Android emulation
cdpilot emulate reset         # Back to desktop

Geolocation

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

Accessibility

cdpilot a11y                  # Full accessibility tree
cdpilot a11y summary          # Quick summary
cdpilot a11y find <role>      # Find elements by ARIA role

Session Management

cdpilot session               # Current session info
cdpilot sessions              # List all sessions
cdpilot session-close [id]    # Close session

Advanced

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

Use with AI Agents

cdpilot is designed to be called by AI agents as a tool:

Claude Code (MCP)

{
  "mcpServers": {
    "cdpilot": {
      "command": "npx",
      "args": ["cdpilot", "mcp"]
    }
  }
}

Any LLM (tool-use)

{
  "name": "browser",
  "description": "Control a browser via CDP",
  "parameters": {
    "command": "go https://example.com"
  }
}

Python (subprocess)

import subprocess
result = subprocess.run(["npx", "cdpilot", "go", url], capture_output=True, text=True)
print(result.stdout)

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

How It Works

┌─────────────┐     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.

Comparison

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

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 querySelector are JSON-escaped to prevent injection.
• No network exposure — CDP listens on 127.0.0.1 only. 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.

Roadmap

The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:

Shipped

• [x] 60+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
• [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
• [x] 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
• [x] Accessibility tree snapshot (a11y-snapshot) — structured data with @ref references, 500x fewer tokens than screenshots
• [x] Token-efficient screenshots — element-level crop (13x smaller), JPEG quality control, format selection
• [x] Vision fallback (describe) — a11y + screenshot + text in one call
• [x] Annotated screenshots — @N badge overlays on interactive elements
• [x] Auto-wait — MutationObserver-based, 5s automatic element waiting
• [x] Batch commands — pipe JSON arrays via stdin for multi-step automation
• [x] Visual feedback system (persistent green glow, cursor, ripples, keystroke display)
• [x] AI control warning toast (red warning when user interacts during automation)
• [x] Multi-project browser isolation (each project gets its own port + profile)
• [x] Pre-flight wizard (auto-installs dependencies on first run)
• [x] Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
• [x] DevExtension system (native JS injection without browser store)

Coming Soon

• [ ] iframe & Shadow DOM support — interact with elements inside iframes and shadow roots
• [ ] 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

git clone https://github.com/mehmetnadir/cdpilot.git
cd cdpilot
npm install
npm test

PRs welcome! Please read CONTRIBUTING.md first.

License

MIT — do whatever you want.

---

<p align="center"> Built with the <a href="https://github.com/mehmetnadir/cdpilot">cdpilot</a> mindset: one tool, one job, done right. </p>