cdpilot

Automatización de navegador sin dependencias desde tu terminal. Un comando, control total.

Inicio rápido

npx cdpilot launch    # Start browser with CDP
npx cdpilot go https://example.com
npx cdpilot shot      # Take screenshot

Sin archivos de configuración. Sin código repetitivo. Solo npx y listo.

¿Por qué cdpilot?

Los agentes de IA y los desarrolladores necesitan un control del navegador que simplemente funcione:

• Configuración cero — npx cdpilot launch inicia una sesión de navegador aislada

• Sin dependencias — Sin Puppeteer, sin Playwright, sin Selenium. CDP puro sobre HTTP

• Más de 40 comandos — Navegar, hacer clic, escribir, capturas de pantalla, red, consola, accesibilidad y más

• Amigable con agentes de IA — Diseñado para Claude, GPT, Gemini y cualquier flujo de trabajo de uso de herramientas de LLM

• Sesiones aisladas — Tu navegador personal permanece intacto. cdpilot se ejecuta en su propio perfil

• Retroalimentación visual — Superposición de brillo verde, visualización del cursor, ondas de clic y visualización de pulsaciones de teclas te mantienen informado durante la automatización

• Aislamiento de multiproyectos — Cada proyecto obtiene su propia instancia de navegador y puerto automáticamente, sin conflictos

• Advertencia de control de IA — Aparece una notificación emergente roja cuando pasas el cursor durante la automatización activa

• Privacidad primero — Todo se ejecuta localmente. Ningún dato sale de tu máquina

¿Por qué Brave?

cdpilot utiliza Brave Browser como su motor. He aquí por qué:

En resumen: Brave = Potencia de Chrome + privacidad integrada + menos peso. Perfecto para la automatización.

cdpilot también funciona con Chrome y Chromium como alternativa. Brave es recomendado, no obligatorio.

Instalación

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

# Or install globally
npm i -g cdpilot

Requisitos: Node.js 18+ y uno de los siguientes: Brave Browser, Google Chrome o Chromium.

Configuración inicial

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

Comandos

Navegación y contenido

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

Interacción

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

Depuración

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

Gestión de pestañas

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

Control de red

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

Intercepción de solicitudes

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

Emulación de dispositivos

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

Geolocalización

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

Accesibilidad

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

Gestión de sesiones

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

Avanzado

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

Uso con agentes de IA

cdpilot está diseñado para ser llamado por agentes de IA como una herramienta:

Claude Code (MCP)

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

Cualquier LLM (uso de herramientas)

{
  "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)

Variables de entorno

Cómo funciona

┌─────────────┐     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
       └────────────────────────────────────────┘

Sin Puppeteer. Sin Playwright. Sin Selenium. Solo comunicación directa con CDP.

Comparación

Monetización / Pro (Próximamente)

La CLI de cdpilot es y siempre será gratuita y de código abierto (MIT).

Futuras ofertas de pago:

• cdpilot cloud — Instancias de navegador remotas, no se necesita navegador local

• Panel de equipo — Sesiones compartidas, registros de auditoría, análisis de uso

• Soporte prioritario — Ayuda directa para integraciones empresariales

Seguridad

• Perfil de navegador aislado — cdpilot se ejecuta en ~/.cdpilot/profile, separado de tu navegador diario. Tus cookies, contraseñas e historial nunca quedan expuestos.

• Sin acceso arbitrario a archivos — Los nombres de archivo de las capturas de pantalla de MCP se desinfectan y se limitan al directorio de capturas de pantalla. El recorrido de rutas está bloqueado.

• Selectores CSS seguros — Todos los selectores pasados a querySelector se escapan en JSON para evitar inyecciones.

• Sin exposición a la red — CDP escucha solo en 127.0.0.1. Las conexiones remotas no son posibles por defecto.

• Sin dependencias — Cero dependencias de tiempo de ejecución de npm/Python significa cero superficie de ataque en la cadena de suministro.

¿Encontraste una vulnerabilidad? Por favor, envía un correo electrónico directamente al mantenedor en lugar de abrir un problema público.

Hoja de ruta

El único MCP de navegador con aserciones de prueba integradas. Esto es lo que hemos lanzado y lo que viene:

Lanzado

• [x] Más de 60 comandos CLI (navegar, hacer clic, rellenar, captura de pantalla, PDF, consola, red...)

• [x] Servidor MCP para integración con agentes de IA (Claude Code, Cursor, etc.)

• [x] 10 aserciones de prueba integradas — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff

• [x] Instantánea del árbol de accesibilidad (a11y-snapshot) — datos estructurados con referencias @ref, 500 veces menos tokens que las capturas de pantalla

• [x] Capturas de pantalla eficientes en tokens — recorte a nivel de elemento (13 veces más pequeño), control de calidad JPEG, selección de formato

• [x] Respaldo de visión (describe) — a11y + captura de pantalla + texto en una sola llamada

• [x] Capturas de pantalla anotadas — superposiciones de insignias @N en elementos interactivos

• [x] Auto-espera — basado en MutationObserver, espera automática de elementos de 5s

• [x] Comandos por lotes — canaliza matrices JSON a través de stdin para automatización de varios pasos

• [x] Sistema de retroalimentación visual (brillo verde persistente, cursor, ondas, visualización de pulsaciones de teclas)

• [x] Advertencia de control de IA (advertencia roja cuando el usuario interactúa durante la automatización)

• [x] Aislamiento de navegador por proyecto (cada proyecto obtiene su propio puerto + perfil)

• [x] Asistente de pre-vuelo (instala automáticamente las dependencias en la primera ejecución)

• [x] Brillo MCP persistente (permanece encendido durante toda la sesión de IA, como el brillo naranja de Claude)

• [x] Sistema DevExtension (inyección JS nativa sin tienda de navegadores)

• [x] Comandos inteligentes — smart-click, smart-fill, smart-select — interactúa por texto visible, no se necesitan selectores CSS, no se requiere LLM

• [x] Extracción de datos (extract) — datos DOM estructurados en formato de texto, JSON o lista

• [x] Observación de página (observe) — lista todos los elementos interactivos con acciones disponibles

• [x] Ejecutor de scripts (run) — ejecuta archivos de script .cdp con informes de éxito/fallo

Próximamente

• [ ] Soporte para iframe y Shadow DOM — interactúa con elementos dentro de iframes y shadow roots

• [ ] Grabación y reproducción de sesiones — graba sesiones de navegador y reprodúcelas de forma determinista

• [ ] Modo sigilo (Pro) — ratón/escritura similar al humano, anti-huellas digitales, resolución de CAPTCHA

• [ ] cdpilot Cloud — API de sesiones de navegador alojadas, punto final MCP REST + WebSocket

• [ ] Extensión de Chrome — usa cdpilot desde cualquier navegador sin CLI

• [ ] Auditoría de rendimiento — Core Web Vitals (LCP, CLS, INP) a través del dominio de rendimiento de CDP

• [ ] Auditoría de accesibilidad WCAG — informes de cumplimiento de a11y automatizados

• [ ] Modo Claude Code Skill — ejecutar como una habilidad de .claude/skills/ además de MCP

¿Tienes una idea? Abre un problema o envía un PR!

Contribuyendo

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

¡Los PR son bienvenidos! Por favor, lee CONTRIBUTING.md primero.

Licencia

MIT — haz lo que quieras.