OpenCode Pilot — Dashboard remoto para OpenCode

// 01 · El problema

OpenCode corre perfecto mientras estés frente a él.

OpenCode es un agente de IA que corre en tu terminal. Funciona perfecto mientras estés sentado frente a él — pero en cuanto te levantás, todo se frena. El agente pide permiso para ejecutar un comando, no hay nadie para aprobarlo. Querés seguir la ejecución desde el teléfono mientras hacés otra cosa, no podés. Abrís otro proyecto en otra terminal y perdés el hilo de lo que estaba haciendo el primero.

📋

Aprobar permisos sin estar frente a la terminal

Herramientas peligrosas necesitan aprobación, pero no estás ahí.

📱

Seguir sesiones largas desde el sofá

Desde el móvil, otro laptop o cualquier dispositivo en tu red.

🔄

Coordinar varios proyectos simultáneos

Cada uno con su tab. Cambiás de contexto sin perder sesiones.

🔔

Recibir notificaciones cuando termina

Web Push o Telegram — en tiempo real, sin estar en el dashboard.

👥

Compartir el dashboard con colegas

Pair programming asincrónico detrás de un túnel público.

// 02 · Features

Todo lo que OpenCode hace, accesible desde el navegador.

Un servidor HTTP+SSE corre dentro del proceso de OpenCode. El dashboard es una SPA de módulos ES nativos servida desde el mismo origen — sin React, sin build, sin latencia.

▦

Dashboard multi-proyecto

Pestañas para todos los proyectos que abriste con OpenCode. Cambiás de contexto sin perder sesiones. Cada tab recuerda sus propias sesiones, mensajes y estado.

⇄

Streaming en vivo vía SSE

Cada token de la respuesta aparece a medida que OpenCode lo genera. Sin recargar, sin polling, sin latencia. Efecto typewriter real.

✓

Aprobación remota de permisos

Cuando el agente pide permiso para ejecutar una herramienta, aparece un banner en el dashboard — desde tu celular también. Aprobás o rechazás con un toque. Si hay cola, se muestra el contador 1/N.

⌨

Command palette + shortcuts

Ctrl/Cmd + K abre la paleta. Cambiás de agente, de modelo, de proveedor, creás sesión nueva, cambiás de proyecto — todo con teclado.

⚙

Settings UI

Configurás puerto, host, túnel, Telegram, VAPID keys, timeouts y más desde una modal. Se guarda atómicamente en ~/.opencode-pilot/config.json.

📂

Browser de archivos con glob

Explorás el árbol de archivos del proyecto, buscás por patrón glob con debounce, y abrís archivos para ver su contenido (opt-in).

↗

Web Push (VAPID)

Recibís notificaciones aunque el dashboard esté cerrado. Se generan las claves VAPID desde Settings con un clic.

✈

Bot de Telegram

Configurás token + chat ID (con hints en el dashboard). Recibís alertas de permisos, errores y fin de sesión en Telegram.

!

Browser notifications

Usa la Notifications API nativa cuando el permiso está concedido. Notificaciones inline sin perder la sesión.

▤

PWA y soporte móvil

La interfaz es responsive. Podés instalar el dashboard como app desde el menú del navegador. Service worker con cache versionado y detección de cambios de red.

⚏

QR pairing

Un QR para LAN, otro para túnel público. Empareja en segundos desde el celular.

🔗

Auto-focus de la carpeta activa

/remote levanta el dashboard y automáticamente enfoca la pestaña de la carpeta donde estás trabajando. Si no existe, la crea.

📝

Prompt desde el móvil

Envía prompts, aprueba permisos y cambia agentes como si estuvieras en el escritorio.

🌐

Túnel público opcional

PILOT_TUNNEL=cloudflared (o ngrok) y el plugin levanta un túnel automático, detecta la URL, te la muestra en el dashboard y genera un QR.

📊

Welcome card + onboarding

Primer visitante del dashboard ve un checklist de 4 pasos. Se descarta para siempre con un clic.

🔄

Recuperación de token automática

Si OpenCode reinició y tu token quedó stale, la pantalla de "token inválido" te deja pegar la URL fresca y extrae el nuevo token sola.

🔧

CLI con doctor y uninstall

bunx @lesquel/opencode-pilot doctor hace 6 checks de salud en <2 segundos. uninstall revierte toda la instalación (opcional --keep-config).

💡

Hints y validación inline

Cada campo de Settings tiene un hint con dónde conseguir el valor. Al perder foco, valida formato básico sin bloquear el save.

// 03 · Live dashboard

Una SPA vanilla que parece nativa.

Click en las sesiones para ver cómo cambia la transcripción. Todo corre desde el mismo origen que el proceso de OpenCode — cero latencia artificial.

https://localhost:4097/?token=4a9c…

Connected · SSE

agent · build refactor SSE reconnect $0.42 · 12.4k tok

U

La reconexión SSE se vuelve loca cuando cambio de red. ¿Puedes añadir backoff exponencial y un pong explícito?

A

Entendido. Añadiré backoff exponencial (1s → 30s máx) y un heartbeat cada 15s con timeout. Voy a editar src/dashboard/sse.ts.

◈ edit src/dashboard/sse.ts completed · 142ms

-  const delay = 1000;
+  const delay = Math.min(30_000, 1_000 * 2 ** attempts);
+  scheduleHeartbeat(15_000);

◈ bun test sse.test.ts running…

[sse] 4 pass · 0 fail · 0 skip
[runtime] ✓ reconnects with jittered backoff
[runtime] ✓ heartbeat fires every 15s

⌘↵

// 04 · Cómo funciona

Arquitectura en tres componentes.

El plugin corre dentro del proceso de OpenCode, expone un servidor HTTP+SSE, y el dashboard se conecta vía Bearer token.

┌─────────────────────┐      ┌─────────────────────┐
│   OpenCode TUI      │      │   Dashboard web     │
│   (tu terminal)     │      │   (cualquier navegador)│
└──────────┬──────────┘      └──────────┬──────────┘
           │                            │
           │    hooks del SDK           │    HTTP + SSE
           │                            │
           └──────────┬─────────────────┘
                      │
           ┌──────────▼──────────┐
           │  Plugin server      │
           │  (Bun.serve)        │
           │                     │
           │  • Permisos queue   │
           │  • Event bus (SSE)  │
           │  • Settings store   │
           │  • Audit log        │
           │  • Telegram bot     │
           │  • Tunnel service   │
           │  • Web Push         │
           │  • Multi-instance   │
           │    coordinator      │
           └─────────────────────┘

1. Instalás

bunx @lesquel/opencode-pilot init. El CLI edita opencode.json y tui.json para registrar el plugin.

2. Reabrís OpenCode

El plugin arranca un servidor HTTP en 127.0.0.1:4097, escribe el token en ~/.opencode-pilot/pilot-state.json, y carga los slash commands.

3. Corrés /remote

El plugin abre tu navegador con un hash #dir=<carpeta-actual> que el dashboard usa para auto-enfocar la pestaña correcta.

// 05 · Instalación

Un comando. Tres pasos. Cero configuración.

El instalador localiza tu config dir de OpenCode (XDG, APPDATA, etc.), registra el plugin en opencode.json y tui.json, y limpia wrappers viejos.

Pre-requisitos

OpenCode instalado (npm i -g opencode o tu método preferido). Bun (recomendado) o Node moderno.

✓ OpenCode ≥ 0.1.0 · ✓ Node 18+ o Bun · ✓ APPDATA/XDG_CONFIG_HOME accesibles

Ejecuta el init

Una sola línea. Detecta XDG_CONFIG_HOME / APPDATA automáticamente.

$bunx @lesquel/opencode-pilot init

Reabre OpenCode

Cierra todas las sesiones TUI y reabre. Verás un toast: "Remote control plugin loaded".

$opencode

Abre el dashboard

Tipeá /remote en el TUI. Se abre el navegador. El banner imprime URL, token y QR.

›/remote

Desinstalar

$bunx @lesquel/opencode-pilot uninstall

Borra todo (config + state)

$bunx @lesquel/opencode-pilot uninstall --keep-config

Preserva ~/.opencode-pilot/config.json

Diagnóstico

$bunx @lesquel/opencode-pilot doctor

Reporta en <2s: plugin instalado, config edits presentes, OpenCode corriendo, pilot responsivo, state file válido.

// 06 · Casos de uso

Situaciones reales en las que OpenCode Pilot cambia el juego.

Desarrollador solo que quiere aprobar desde el celular

Tu agente está ejecutando un refactor largo. Te levantás a hacer café. En el celular, una notificación Web Push te avisa que el agente pide permiso para ejecutar rm -rf node_modules. Aprobás desde el celular con un toque.

Equipo que colabora revisando sesiones

Activás el túnel (PILOT_TUNNEL=cloudflared). El dashboard queda accesible con un link público. Un colega sigue la sesión en tiempo real para hacer pair programming asincrónico.

Quien trabaja en varios proyectos simultáneos

Tenés OpenCode corriendo en 3 terminales distintas, en 3 proyectos distintos. Abrís el dashboard y las 3 aparecen como pestañas. Cambiás entre proyectos sin perder estado.

Debug de sesiones remotas

Necesitás ver qué hizo el agente hace 2 horas en el servidor de CI. Te conectás al túnel, abrís la sesión en el dashboard, leés el histórico completo, descargás el diff.

Integración con notificaciones del equipo

Bot de Telegram conectado a un canal del equipo. Cada vez que un agente termina una tarea larga, el canal recibe el resumen. Todo el equipo ve el progreso sin cargar un dashboard.

Testing en múltiples redes

PILOT_HOST=0.0.0.0 en desarrollo, cloudflared en producción. Mismo código, diferente alcance. Ideal para testing con múltiples dispositivos.

// 04 · Mobile

Desde el sofá, la cama, o un hotel en Tokio.

Misma WiFi con PILOT_HOST=0.0.0.0, o expón un túnel público con Cloudflare o ngrok. El dashboard es mobile-first: drawer sidebar, bottom-sheets, 44×44 tap targets.

LAN

PILOT_HOST=0.0.0.0

Tunnel

PILOT_TUNNEL=cloudflared

Shortcut

c

🔒 La URL de túnel contiene el token. Trátala como una contraseña — rota con /pilot-token.

Connect phone

Scan with camera app

192.168.1.14:4097/?t=4a9c…

Same WiFi · 44ms

// 05 · Keybinds & commands

Todo es un atajo.

Para quienes prefieren teclear antes que hacer click. Pulsa ? dentro del dashboard para la paleta completa.

Keyboard shortcuts global · sin input focused

Command palette · paleta + shortcuts

?

Command palette (modifier)

⌘ K

Nueva sesión

n

Toggle sidebar

s

Toggle multi-view

m

Toggle tema

t

Conectar móvil

c

Enfocar prompt

/

Enviar prompt

⌘ ↵

Toggle info panel

⌥ I

Cerrar modal/palette

Esc

Slash commands desde OpenCode TUI

/pilot · URL + token actual

/pilot

/pilot-token · rota el token, invalida dashboards abiertos

/pilot-token

/dashboard · alias de /pilot

/dashboard

/remote · info de conexión (host, port, tunnel)

/remote

/remote-control · status completo + hint de QR

/remote-control

Si los slash commands no aparecen, verifica que tui.json::plugin incluye el spec. OpenCode usa dos loaders — uno para el servidor, otro para la TUI — y necesitan registros separados.

// 06 · Config

Dos caminos: UI o .env.

Desde v1.12 editas todo desde el icono de engranaje. Los valores viven en ~/.opencode-pilot/config.json. Si prefieres archivos, un .env también funciona — y las env vars del shell siempre ganan.

Prioridad → 1. shell env · 2. Settings UI · 3. .env · 4. defaults

Variable	Default	Descripción
PILOT_PORT	4097	Puerto del servidor HTTP
PILOT_HOST	127.0.0.1	Dirección de bind. `0.0.0.0` para LAN.
PILOT_TUNNEL	—	`cloudflared` o `ngrok` para acceso público
PILOT_PERMISSION_TIMEOUT	300000	Timeout de solicitud de permiso en ms
PILOT_TELEGRAM_TOKEN	—	Bot token de @BotFather para notificaciones Telegram
PILOT_TELEGRAM_CHAT_ID	—	Chat ID al que enviar las alertas
PILOT_VAPID_PUBLIC_KEY	—	Clave pública Web Push (genera con un click en Settings)
PILOT_VAPID_PRIVATE_KEY	—	Clave privada Web Push
PILOT_ENABLE_GLOB_OPENER	false	Habilita `/fs/glob` para búsqueda glob desde el dashboard
PILOT_FETCH_TIMEOUT_MS	10000	Timeout para llamadas HTTP salientes (Telegram, push)

// 07 · Docs

Documentación completa.

El docs/ del repo cubre desde la arquitectura de loaders hasta el diseño futuro del relay.

docs/CONFIGURATION.md

Configuration reference

Cada env var, con .env de ejemplo para escenarios comunes.

read →

docs/INSTALL.md

Two-loader architecture

Por qué OpenCode necesita dos entradas de plugin y cómo debuggearlas.

read →

docs/TUNNEL_TESTING.md

Tunnel testing

Guía end-to-end de verificación del túnel, con security checklist.

read →

docs/PHONE.md

Connect from phone

Setup de LAN y de túnel, con screenshots y troubleshooting.

read →

docs/PUBLISHING.md

Publishing to npm

Para contributors que quieran publicar forks del plugin.

read →

docs/RELAY_V2.md

Cloud relay v2.0

Arquitectura de un servicio centralizado futuro. Diseño, no implementación.

read →