opencode-browser-tool-installer/docs/QUICKSTART.md

Quickstart - Browser Tool

Guia corta para dejar la herramienta lista y ejecutar una prueba minima.

1) Instalar

Desde opencode-browser-tool/:

./install.sh

Alternativa neutral por npm/node:

npm run setup

Esto instala dependencias, compila y prepara Chromium managed by Playwright.

2) Compilar

npm run build

2.1) Verificar

./check.sh

3) Configurar MCP en el proyecto

Crear opencode-browser-tool/.opencode/opencode.json con:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "browser-tool": {
      "type": "local",
      "command": [
        "node",
        "/ABSOLUTE/PATH/opencode-browser-tool/dist/server.js"
      ]
    }
  }
}

Nota: ajusta la ruta absoluta de dist/server.js a tu equipo.

4) Verificar conexion MCP

opencode mcp list

Debe aparecer browser-tool como connected.

5) Primera prueba minima

Pide a OpenCode una secuencia simple:

• abrir navegador
• navegar a una URL
• tomar snapshot
• cerrar navegador

Ejemplo de instruccion:

Usa solo browser-tool: abre navegador visible, navega a https://example.com, toma snapshot con label quickstart y cierra navegador.

5.1) Auto-descubrimiento recomendado

Antes de pruebas complejas, pide:

• browser_help
• browser_health
• browser_diagnostics_clear (opcional, para empezar limpio)

Con eso el agente detecta capacidades disponibles, defaults y estado operativo actual.

6) Dónde quedan las capturas

Se guardan en:

• opencode-browser-tool/artifacts/

7) Descubrir capacidades automaticamente

Usa las tools browser_help y browser_health al inicio de una sesion para que el agente reciba capacidades, defaults y estado de ejecucion.

Para incidencias durante pruebas, usa browser_diagnostics para extraer consola, errores de pagina y requests fallidas. Si un flujo no avanza, usa browser_observe para capturar estado intermedio y browser_handle_consent para resolver banners.

8) Grabacion bajo demanda (video/trace)

Para sesiones complejas, abre con grabacion:

• recordVideo: true
• recordTrace: true
• recordLabel: "caso-xyz"

Los artifacts se cierran y quedan disponibles al ejecutar browser_close.

9) Reporte consolidado de ejecucion

Al finalizar un flujo, puedes pedir:

• browser_report con format: both

Nota: por defecto la herramienta ya deja saveToFile=true al instalar.

Esto deja resumen tecnico en JSON y lectura humana en Markdown dentro de artifacts/.

Si quieres cambiar ese default de forma persistente, usa browser_config con action: set.

10) Elegir navegador: testing o system

Por defecto, browser_open usa browserKind: testing (Playwright managed).

Si necesitas perfil real de usuario, puedes usar navegador del sistema:

{
  "browserKind": "system",
  "persistentProfile": true,
  "userDataDir": "/home/pancho/.chrome-perfil-google-real",
  "startUrl": "https://www.google.com"
}

Tambien puedes fijarlo de forma persistente con browser_config (browserDefaultKind, browserDefaultPersistentProfile, browserDefaultUserDataDir).

11) Verbose y delay humano (default activo)

Por defecto, browser_open aplica:

• verbose: true
• verboseOverlay: true (en modo visible)
• interactionDelayMinMs: 1000
• interactionDelayMaxMs: 3000

Puedes desactivar verbose por ejecucion:

{
  "verbose": false,
  "verboseOverlay": false
}

Y puedes ajustar delays por ejecucion:

{
  "interactionDelayMinMs": 800,
  "interactionDelayMaxMs": 1800
}