cdpilot

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

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:

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

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

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

We're building cdpilot into the lightweight alternative to Playwright MCP for AI agents. Here's what's coming:

• 40+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
• MCP server for AI agent integration (Claude Code, etc.)
• Visual feedback system (green glow, cursor visualization, click ripples, keystroke display)
• AI control warning toast (appears when user tries to interact during automation)
• Multi-project browser isolation (each project gets its own port + profile automatically)
• DevExtension system (native JS injection without browser store)
• Accessibility tree snapshot — structured a11y data for AI agents (like Playwright MCP but 4x lighter)
• Annotated screenshots — element references (@e1, @e2) overlaid on screenshots for precise AI clicking
• Auto-wait — automatically wait for elements before interaction (reduce flakiness)
• Batch commands — pipe JSON arrays via stdin for multi-step automation in one call
• iframe & Shadow DOM support — interact with elements inside iframes and shadow roots
• Claude Code Skill mode — run as a .claude/skills/ skill in addition to MCP
• Session recording & replay — record browser sessions and replay them deterministically
• Stealth mode — anti-detection flags for web scraping scenarios

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.

Built with the cdpilot mindset: one tool, one job, done right.