cdpilot

# cdpilot

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

[![npm version](https://img.shields.io/npm/v/cdpilot.svg)](https://www.npmjs.com/package/cdpilot)
[![npm downloads](https://img.shields.io/npm/dm/cdpilot.svg)](https://www.npmjs.com/package/cdpilot)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![cdpilot MCP server](https://glama.ai/mcp/servers/mehmetnadir/cdpilot/badge)](https://glama.ai/mcp/servers/mehmetnadir/cdpilot)

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

## Quick Start

```bash
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:

| Your workload | Auto-pick order |
|---|---|
| Has extensions registered (`ext-install`) | vivaldi → brave → edge → chromium → chrome |
| No extensions (pure automation) | chrome → vivaldi → edge → chromium → brave |

Override anytime:

```bash
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

```bash
# 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

```bash
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:

```bash
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](CHANGELOG.md) for the full list with rationale.

## Commands

### Navigation & Content

```bash
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

```bash
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`:

```bash
# 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
```

- Works for `click`, `fill`, `type`, `submit`, `hover`, `dblclick`, `rightclick`,
  `smart-click`, `smart-fill`, `smart-select` and `frame list|eval|shadow`.
- A frame hop is a CSS selector, a 0-based index, a `name`/`id`, or
  `url=<src substring>`. `--frame` also takes a bare `src` substring.
  `>>>` inside quotes or `[...]` is literal. A selector that matches an
  element *wrapping* an iframe (Stripe's `#card-element`) enters the iframe
  inside it and says so on stderr:
  `note: '#card-element' is not an iframe; using the iframe inside it`.
- Selectors and texts that already contain `>>>` keep working: when the part
  before the first `>>>` finds no iframe in the page, or a segment is empty
  (`click "Next >>>"`), the whole string is used as written, exactly as
  before. If that fails too, one stderr line explains:
  `note: 'Home' matched no iframe; used the selector as written`.
  `--frame` never falls back: a frame it cannot find is an error (exit 1).
- For `smart-click` / `smart-fill` / `smart-select` the part before the first
  `>>>` is a frame only if it looks like a selector (it has `#`, `.` or `[`,
  or starts with an `iframe`/`frame` tag) or is `url=…`; words stay text.
  `smart-click "Main >>> Settings"` clicks the page's "Main >>> Settings"
  link even when a `<main>` element holds an iframe. For a frame index or a
  bare name use `--frame`.
- Same-origin **and cross-origin** frames work, including out-of-process
  iframes (site isolation): cdpilot resolves each hop over CDP
  (`DOM.describeNode` → frame id → the frame's execution context, or
  `Target.attachToTarget` with a flat session for an out-of-process frame),
  never through `contentDocument`, which the browser blocks cross-origin.
- Real mouse input (`hover`, `dblclick`, `rightclick`, `--entropy=on` clicks)
  is dispatched at page coordinates: the frame's offset in the page is added
  automatically, so the browser hit-tests into the right frame.
- `smart-click` / `smart-fill` / `smart-select` look in the page first and
  compare texts with whitespace collapsed (`&nbsp;` and line breaks count as
  one space). An enabled page element whose text or label contains the whole
  query is used. If the page's only such elements are disabled, the command
  fails as before (`no enabled element matches …`) without looking in frames.
  Otherwise the visible frames are searched breadth-first for a whole-query
  match (at most 20 frames, and 2 s for all of the search's CDP calls) and the
  match is reported on stderr:
  `smart-click: matched inside frame iframe#card (https://…)`. The search only
  looks (no click, no typing); the command then acts once, in the chosen
  frame. With no frame match, the page's partial (word) match is used as
  before. When the 2 s run out:
  `smart-click: frame search stopped after 2s (3 of 7 frames)`; a frame that
  had not answered by then has not been touched.
- `smart-fill` and `smart-select` search automatically only frames of the
  page's own origin, so a typed value never lands in a third-part