# ⚡ Fast Browser Harness

**Controla tu Chrome real desde tu agente de IA. Sin reiniciar, sin perfiles falsos, sin fricción.**

Fast Browser Harness se adhiere por CDP al Chrome que ya tienes abierto — con tus tabs, tus logins y tu IP — y lo opera en segundo plano: clicks, escritura, navegación, snapshots atómicos, screenshots, grabación de video y servidor MCP. Tu tab visible ni parpadea.

```bash
pip install fast-browser-harness
fast-browser-harness --doctor
echo 'print(page_info())' | fast-browser-harness
```

> Proyecto independiente con branding propio. Sin relación con ningún otro proyecto. Telemetría **apagada por defecto**. Origen del código base: ver [Atribución](#atribución).

---

## Por qué existe

Los automatizadores clásicos levantan su propio navegador estéril: sin cookies, sin sesión, con IP de datacenter. Sirven para CI, pero para trabajo real (revisar tu consola de Neon, operar tu admin, descargar tu factura) son inútiles: tendrías que loguearte a mano en cada corrida o pasarle tus credenciales al agente.

Fast Browser Harness invierte el modelo: **el agente entra a tu navegador, no tú al suyo.**

## Pros, a detalle

### 1. Cero fricción real

- **No cierras nada.** Se conecta al Chrome en ejecución. Sin `--remote-debugging-port` manual, sin perfiles paralelos, sin "reinicia con este flag".
- **Si Chrome está cerrado, lo abre solo** y reintenta la conexión.
- **Si falta el permiso de debugging**, abre `chrome://inspect/#remote-debugging` y te guía (en macOS, `mac-approve`; en Linux Snap, `--fix-snap`).
- **Tabs de fondo.** `new_tab()` y `switch_tab()` trabajan sin cambiar tu tab visible. Solo `activate_tab()` toma la pantalla, y solo cuando lo pides o la página lo exige.
- **Diagnóstico en un comando:** `fast-browser-harness --doctor` (también `--json`).
- **Marcador discreto** en el título del tab anexado (desactivable con `BH_TAB_MARKER=0`).

### 2. Velocidad por arquitectura, no por promesas

Sin números inventados: esto es lo que lo hace rápido y cómo medirlo tú.

- **CDP directo, sin WebDriver en el medio.** Cada acción es un mensaje al renderer, sin servidor intermedio ni polling de estado.
- **Un snapshot atómico por observación.** Una sola llamada trae controles visibles, nombres accesibles, valores y texto. Nada de N idas y vueltas para mapear la página.
- **Sin screenshots en el loop.** El operador consume estado estructurado; las capturas son opt-in (inspector, evidencia, video).
- **Esperas mínimas y útiles.** Tras escribir en un combobox espera sugerencias visibles (tope 200 ms); otras interacciones, dos frames o 50 ms. Sin `sleep(2)` a ciegas.
- **Validación antes de actuar.** Cada click rechequea frescura del documento, geometría y oclusión. Falla temprano con el elemento que tapa, en vez de clickear al vacío y reintentar todo el flujo.
- **Tabs ocultos que siguen renderizando.** Emulación de foco evita que Chrome estrangule animaciones en background, sin robarte la pantalla.

**Cómo medirlo tú mismo:**

```bash
time (echo 'print(page_info())' | fast-browser-harness)
# Cuenta llamadas CDP de una tarea con recordings enable + productions logs
fast-browser-harness recordings enable
```

Si publicas números, publica también máquina, red y tarea. Un benchmark sin contexto es marketing.

### 3. Sesiones logueadas sin regalar credenciales

El agente nunca ve tu password: opera sobre tu sesión existente (cookies, storage, SSO). Para nubes o sub-agentes paralelos existe modo remoto (`start_remote_daemon`) y sincronización de perfil por cookie. Flujos con login/2FA los haces tú una vez en tu Chrome; el agente trabaja después.

### 4. Pasa más muros bot (y aquí va la parte honesta)

**Qué ayuda, en orden de impacto:**

1. **IP real.** Sales con tu IP residencial/de oficina, no con rango de datacenter marcado. Esto solo ya resuelve la mayoría de bloqueos.
2. **Perfil real.** Historial, cookies, idioma, zona horaria, fuentes y WebGL intactos: la huella parece una persona porque *es* la tuya.
3. **Eventos de entrada reales.** Clicks y teclas viajan por CDP como entrada genuina, no como `element.click()` inyectado ni formularios rellenados por JS.
4. **Sin banderas headless.** Es tu Chrome visible normal, no `--headless` con sus huellas clásicas.
5. **Ritmo no mecánico.** Esperas atadas a estado visible (sugerencias, carga) en vez de sleeps fijos.

**Límites honestos — léeme antes de prometer "indetectable":**

- **Nada es indetectable.** Bajo CDP, `navigator.webdriver` y otras señales pueden delatar automatización frente a scripts que las buscan. No hacemos spoofing de fingerprint (a propósito: tu huella real es mejor camuflaje que una falsa).
- **El comportamiento delata.** Loops deterministas a toda velocidad *parecen* bots. La velocidad es una ventaja operativa, no de sigilo: si un sitio te limita, baja el ritmo, no lo fuerces.
- **Los captchas pueden aparecer igual.** Este harness no los resuelve; te deja la página servida para que los resuelvas tú.
- **Respeta ToS y rate limits.** Si un sitio dice no a bots, este README no es un permiso.

### 5. Operación para agentes, no solo scripts

- **Skill empaquetada:** `fast-browser-harness skill` imprime el flujo exacto que debe seguir un agente (un tab por tarea, no duplicar, no cerrar lo ajeno).
- **Servidor MCP:** `fast-browser-harness-mcp` expone las ayudas por stdio (`browser_new_tab`, `browser_click`, `browser_js`, `browser_cdp`…).
- **Grabación y video:** sesiones reproducibles y exportación MP4 verificable.
- **Navegadores remotos opcionales** para headless, paralelismo o aislamiento (requiere cuenta/servicio externo).

## Comparativa honesta

| | Fast Browser Harness | agent-browser (Vercel) | Playwright / Selenium |
|---|---|---|---|
| Navegador | Tu Chrome en uso | Chromium propio descargado (~200 MB) | El que configures |
| Sesiones/logins | Los tuyos, cero setup | Ninguno (aislado) | Los que programes |
| Fricción | Cero (sin reiniciar) | Media-alta (instalar, flags) | Alta (código + waits) |
| Muros bot | IP + perfil reales | IP/entorno de bot típicos | Según tu setup |
| Ideal para | Trabajo diario con logins | CI, tests reproducibles | Frameworks a medida |
| Aislamiento | Bajo (ve tu navegador) | Alto | El que diseñes |

Aislamiento vs adherencia es un tradeoff, no un ranking: para CI quédate con lo aislado; para operar tu web logueada, adherirse gana.

## Instalación

Requiere Python ≥ 3.11 y tu Chrome/Chromium de todos los días.

```bash
pip install fast-browser-harness
fast-browser-harness --doctor
```

Desde fuente:

```bash
git clone https://github.com/YankielDBC2/fast-browser-harness
cd fast-browser-harness
pip install -e ".[mcp]"
```

## Uso

```bash
# Estado
fast-browser-harness --doctor

# Una observación (los helpers vienen pre-importados)
echo 'print(page_info())' | fast-browser-harness

# Trabajar en un tab nuevo sin tocar tu tab visible
echo 't = new_tab("https://example.com"); print(page_info())' | fast-browser-harness

# Ver el texto (sin secretos a la vista: filtra antes de pegar a un modelo)
echo 'print(list_tabs())' | fast-browser-harness

# Servidor MCP para tu agente
fast-browser-harness-mcp
```

Reglas del skill (resumen): un tab por tarea/sitio, reutiliza con `switch_tab` antes de abrir otro, no dupliques URLs, no cierres tabs ajenos, `activate_tab` solo si te lo piden.

## Variables de entorno

| Variable | Efecto |
|---|---|
| `FBH_HOME` / `BH_HOME` | Directorio de datos (defecto `~/.config/fast-browser-harness`) |
| `FBH_TELEMETRY=1` | Opt-in de telemetría (apagada por defecto) |
| `BH_TELEMETRY=0`, `ANONYMIZED_TELEMETRY=0` | Apagados extra (compatibilidad) |
| `BH_TAB_MARKER=0` | Sin marcador en títulos |
| `BH_DOMAIN_SKILLS=1` | Skills por dominio |
| `BU_NAME` | Nombre del daemon (sesiones paralelas) |
| `BU_CDP_URL` / `BU_CDP_WS` | CDP remoto en vez de Chrome local |
| `BROWSER_USE_API_KEY` | Proxy/nubes (servicio externo, opcional) |

## Telemetría: apagada por defecto

Diferencia deliberada vs upstream: aquí **nada sale de tu máquina salvo que lo pidas**. Sin clave de telemetría empaquetada; para activarla configura `FBH_POSTHOG_KEY` + `FBH_TELEMETRY=1`.

```bash
fast-browser-harness telemetry status
```

## Solución de problemas

- `0 conexiones activas` con Chrome abierto → el harness abre `chrome://inspect`; aprueba el debugging y reintenta.
- macOS pide permiso → `fast-browser-harness mac-approve` (más Accessibility en Ajustes si lo exige).
- Chromium Snap en Linux bloquea CDP → `fast-browser-harness doctor --fix-snap`.
- `--reload` si cambiaste código y el daemon sigue con lo viejo.

## Diferencias vs upstream

- Nuevo nombre, binarios (`fast-browser-harness`, `fast-browser-harness-mcp`) y directorios propios: no choca con el original instalado.
- Telemetría opt-in y sin clave empaquetada.
- Marca de video propia (bolt ⚡) en exportaciones.
- Variables `FBH_*` nuevas; `BH_*`/`BU_*` siguen funcionando.
- Nubes de Browser Use y skills de interacción enlazan a su servicio/documentación original (funcionalidad intacta, atribución visible).

## Atribución

Derivado de [browser-use/browser-harness](https://github.com/browser-use/browser-harness), MIT © 2026 Browser Use. Este fork mantiene su aviso de copyright (ver `LICENSE`) y añade marca, telemetría opt-in y documentación propias. Gracias al equipo de Browser Use por publicar el motor con licencia permisiva.

## Licencia

MIT — ver `LICENSE`.