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
• 70+ commands — Navigate, click, type, screenshot, network, console, accessibility, video understanding, progressive anti-bot resilience, 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

Browser Selection (Workload-Aware Auto-Pick)

cdpilot picks the right browser for what you're doing. auto (default) is a two-axis policy — extension workload × platform stability:

Override anytime:

cdpilot browser            # show current pick + reason
cdpilot browser vivaldi    # pin to Vivaldi
cdpilot browser auto       # restore smart default

Why the split?

• Chrome 147+ silently drops --load-extension for unpacked extensions (no error, no warning). Verified — chrome://extensions shows 0 items.
• Vivaldi, Brave, Edge, Chromium honor --load-extension (tested).
• On macOS 26 (Tahoe) Brave 1.89 crashes deterministically at ~7min uptime (SIGTRAP in ThreadPoolForegroundWorker). cdpilot detects the OS and demotes Brave automatically until a fixed Brave release ships.

Each browser gets its own isolated profile (~/.cdpilot/.../profile-vivaldi etc.) so switching never causes prefs corruption.

Installation

# Use directly (no install needed)
npx cdpilot <command>

# Or install globally
npm i -g cdpilot

Requirements: Node.js 18+, Python 3.10+, and one of: Brave Browser, Google Chrome, or Chromium. (The Python websockets module is auto-installed by the pre-flight wizard on first launch.)

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

Upgrading from 0.4.x → 0.5.0 — read this first

One breaking change, the rest is additive.

Breaking — Visual feedback default flipped to OFF. The green glow border, animated fake cursor, click ripples, and keystroke display made cdpilot feel like an amateur typing on every page. They are now opt-in:

cdpilot show on     # restore the old visual feedback layer
cdpilot show off    # default since 0.5.0

The MCP server's persistent-glow flow (CDPILOT_MCP_SESSION=1) is unchanged — AI agents that rely on visible feedback during a session still see it automatically. Only direct-CLI users see the difference.

New in 0.5.0 (no migration needed):

• cdpilot dismiss — heuristic auto-click for "Stay signed out / No thanks" buttons on LLM chat sign-up walls.
• cdpilot adaptive on — auto-escalate to stealth on CAPTCHA-protected hosts, with persistent per-host memory.
• cdpilot cookies save/load — export/import cookies as JSON to replay CF/DataDome clearance across runs.
• cdpilot context create/list/close + CDPILOT_TARGET — isolated browser contexts for true parallel automation inside a single browser.
• cdpilot fast / cdpilot show — bundled timing + visual toggles.
• Pure performance: post-load sleep 1500ms → 300ms, scrollIntoView instant, WebSocket connection pool, /json TTL cache.

See CHANGELOG.md for the full list with rationale.

Commands

Navigation & Content

cdpilot go <url>              # Navigate to URL (alias: open <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

Element targeting inside iframes

Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA checkbox live inside <iframe>s. Name the frame chain before the element selector with >>>, or pass --frame:

# Payment-style page: the card fields are inside <iframe id="card" title="Secure card payment">
cdpilot fill  "iframe#card >>> input[name=cardnumber]" "4242424242424242"
cdpilot type  --frame "#card" "input[name=cvc]" "123"
cdpilot click "iframe[title='Secure card payment'] >>> button#pay-btn"

# Nested frames: outermost first
cdpilot click "iframe.checkout >>> iframe.card >>> button"

# --frame <selector|index|url-substring>, nestable with >>>
cdpilot click --frame 0 "button.submit"                   # first iframe (same order as `frame list`)
cdpilot fill  --frame "url=js.stripe.com" "input[name=cardnumber]" "4242424242424242"
cdpilot frame list --frame "#card"                        # iframes inside that frame
cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's own page context