App de bandeja (tray) para Windows y Linux que controla el servicio de OpenCode, gestiona el acceso web (local / red / remoto), muestra el consumo de OpenCode Go y permite ver la configuración (MCP / skills / agents).
Estado: funcional — todas las capacidades están implementadas y con tests. Plataformas: 🪟 Windows (distribución oficial:
.exe+ instalador) · 🐧 Ubuntu/Linux (desarrollo y prueba). Planificación:specs/(el qué) ytasks/(el cómo).
Stack: Wails v2.16 + Go 1.25+ + Vue 3 / Vite / TypeScript.
- Antes de empezar
- Inicio rápido — Ubuntu y Windows
- Probar la app — abrir el panel, checklist y problemas frecuentes
- Funcionalidad — qué hace cada pestaña
- Desarrollo — dev, tests y estructura
- Build — Windows —
.exe, instalador y release - Build — Linux/Ubuntu — requisitos, compilar y ejecutar
- Limitaciones conocidas
- Documentación y planificación
| Necesitas | Windows | Ubuntu / Linux |
|---|---|---|
| Go | 1.25+ | 1.25+ |
| Wails CLI | v2.16+ | v2.16+ |
| Node / pnpm | Node 20+ y pnpm 10+ | Node 20+ y pnpm 10+ |
| Librerías del SO | WebView2 (viene con Win10/11) | GTK3 + WebKitGTK 4.1 (ver build) |
| CLI de OpenCode | opencode en el PATH |
opencode en el PATH |
Si wails no se reconoce, instálalo y añádelo al PATH:
go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
export PATH="$HOME/go/bin:$PATH" # queda en ~/go/bin¿Qué quieres hacer?
| Objetivo | Cómo |
|---|---|
| Compilar y probar en Ubuntu (primera vez) | Pasos 1–4 de abajo |
| Recompilar tras un cambio | ./scripts/build-linux.sh |
Instalar como app en Ubuntu (.deb) |
./scripts/build-deb.sh y luego sudo apt install ./dist/*.deb |
Compilar el .exe en Windows |
wails build -clean -webview2 download |
| Correr solo los tests | go test ./... y cd frontend && pnpm test |
Regenerar los iconos (si cambiás brand/) |
./scripts/generate-icons.sh (requiere Chrome/Chromium + Pillow) |
| Desarrollo con hot reload | wails dev (lee las limitaciones) |
# 1) Dependencias del sistema (una sola vez)
sudo apt install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
# 2) Wails CLI (una sola vez)
go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
export PATH="$HOME/go/bin:$PATH"
# 3) Compilar (genera build/bin/opencode-tray)
cd ~/www/opencode-tray
./scripts/build-linux.sh
# 4) Ejecutar (arranca solo con el icono del tray)
./build/bin/opencode-trayEl script detecta WebKitGTK 4.1 y aplica -tags webkit2_41 por ti (Ubuntu 24.04+ ya no trae la 4.0) y fuerza CGO_ENABLED=1. También avisa si faltan las librerías de desarrollo.
# 1) Compilar el portable
wails build -clean -webview2 download
# 2) Ejecutar
.\build\bin\opencode-tray.exeCon instalador per-user: powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1 (detalle en Build — Windows).
- Windows: clic izquierdo en el icono de la bandeja (clic derecho = menú).
- Ubuntu/GNOME: abre el menú del icono y elige Mostrar panel. GNOME no siempre emite el clic izquierdo (
Activate), por eso el panel también está en el menú. Si instalaste el.deb, también puedes lanzarla desde el menú de aplicaciones (abre el panel al arrancar). - No se cierra al hacer clic fuera: el panel permanece abierto al cambiar de ventana. Se oculta con la X de su cabecera, con
Esco con un segundo clic en el icono. Cerrar = ocultar al tray; para salir de verdad usa Salir en el menú.
| # | Comprueba | Resultado esperado |
|---|---|---|
| 1 | Icono en la bandeja | Aparece (PNG en Linux, ICO en Windows) |
| 2 | Consumo del mes | Tooltip en Windows/KDE; en GNOME, primera fila del menú (OpenCode · Mensual ▰▰▱▱▱ 42% · 🕒 en 4 h) |
| 3 | Abrir el panel | Resumen con 4 widgets: consumo, servicio, acceso web y MCP |
| 4 | Pestaña Servicio | Estado + URI real y botones iniciar / detener / forzar / refrescar |
| 5 | Pestaña Acceso web | URLs Local / LAN / Remoto con abrir y copiar |
| 6 | Pestaña Ajustes | Idioma es/en y el panel cambia de idioma al instante |
Si el tooltip muestra consumo, el token de OpenCode Go y la red están bien.
# Linux: lanzar en segundo plano y ver el log
./build/bin/opencode-tray > /tmp/opencode-tray.log 2>&1 &
# Cerrar
pkill -x opencode-trayEn Windows el .exe no abre consola; si necesitas ver errores, usa wails dev (sabiendo su limitación) o ejecuta el .exe desde una terminal.
| Síntoma | Causa | Solución |
|---|---|---|
wails: command not found |
~/go/bin fuera del PATH |
export PATH="$HOME/go/bin:$PATH" |
Package webkit2gtk-4.1 was not found |
faltan los headers | sudo apt install libwebkit2gtk-4.1-dev |
Errores de cgo / CGO_ENABLED=0 |
compilación sin cgo | usa ./scripts/build-linux.sh (lo fuerza) |
| El icono no aparece en GNOME | extensión AppIndicator desactivada | actívala en GNOME Tweaks o usa el menú del tray |
| El clic izquierdo no abre el panel | GNOME no emite Activate |
usa Mostrar panel |
| El panel aparece en otra esquina | Wayland ignora la posición de la ventana | es esperado; en X11/XWayland se respeta |
| Las secciones dicen “Detenido” con el servicio activo | estás en wails dev |
prueba con el build de producción |
- Panel (flyout): ventana frameless anclada al icono del tray, sin marco ni resize. Se abre desde el icono y no se cierra al hacer clic fuera: se oculta con la X de su cabecera (título + cerrar), con
Esco con un segundo clic en el tray. La cabecera sirve de zona de arrastre en Linux; en Windows el panel sigue anclado al icono. Mantiene un alto fijo de 600 px en todas las pestañas y no aparece en la barra de tareas ni en Alt+Tab. Las pestañas tienen tamaño fijo y el scroll reserva su espacio para no deformar el contenido. Al pasar el cursor por el icono, el tooltip nativo muestra el consumo mensual con barra y el reinicio humanizado, y se actualiza aunque el panel nunca se abra. Detalle enspecs/SPEC-shell.md. - Resumen: dashboard de inicio en formato widgets (bento): consumo con las tres barras, servicio con estado/URL, acceso web con icono y color por modo (Local/Red/Remoto) y MCP con chips. Servicio, Acceso y MCP son clicables para saltar a su sección; Consumo mantiene los CTAs de token. Todo es de solo lectura salvo reintentar el token o configurar la API key.
- Servicio (unifica el antiguo Config): estado + URI con puerto y control con etiquetas cortas (iniciar / detener / forzar / refrescar) + servidores MCP + configuración (editor / carpeta / JSON en modal). Los botones muestran su descripción completa al pasar el cursor.
- Acceso web: modos local / red (por IP) / remoto (túnel), exclusivos: al volver a local/red se desactiva el túnel remoto. Muestra las URLs reales con su tipo (Local / LAN / Remoto), botón para abrir en el navegador y botón para copiar con confirmación. El modo remoto pide confirmación explícita (expone el servidor a Internet), se activa con
opencode service set remote truey tolera que OpenCode tarde hasta un minuto en crear el túnel. Detecta el remoto aunque se haya activado desde la app de escritorio (OpenCode 2.x lo guarda como objeto{route}enservice.json). Incluye usuario (opencode), contraseña enmascarada, cambio de contraseña y un botón para refrescar el estado y las URLs. En modo local la URL sale deopencode service status(puerto real); en red/remoto se obtienen de/api/infolas IPs LAN reales y el enlace del túnel. - Ajustes: idioma (es/en), auto-inicio con el sistema (registro en Windows, XDG Autostart en Linux), switches de notificaciones, tarjeta de OpenCode Go (estado del token, reintento desde OpenCode, API key manual cifrada con DPAPI en Windows y base64 en Linux), intervalo de refresco (1/5/15/30/60 min) y tarjeta Acerca de al final con la versión, la compilación (commit + fecha), la plataforma y un botón para copiar la información.
La UI usa iconos SVG (sin emoji), botones btn en tamaño compacto estándar, control segmentado de idioma, switches estilizados y cards con profundidad (design system). El layout es responsive con CSS Grid/Flexbox y container queries, sin dependencias de UI. La navegación es un footer fijo de 4 pestañas (icono + texto) y el contenido es la única zona con scroll. Los datos de Servicio, MCP, Acceso web y Consumo comparten un caché en memoria con claves comunes: volver a una pestaña con datos frescos (10–15 s) no repite la petición ni muestra skeleton. El skeleton aparece solo en la primera carga, en el refresco manual y desde el inicio de una mutación (iniciar/detener el servicio, cambiar modo o contraseña). Las revalidaciones en segundo plano y el polling silencioso del servicio (cada 15 s con el panel visible) sustituyen los datos sin skeleton ni texto de “Actualizando…”. Un cambio hecho en Servicio/Acceso invalida el caché compartido, así que Resumen refleja el nuevo estado (con skeleton mientras llega). La lista de URLs usa 2 filas esqueleto con la misma altura que las filas reales.
wails dev # hot reload (lee la limitación del puente más abajo)
go test ./... # tests backend (Go)
cd frontend && pnpm test # tests frontend (Vitest): 79 tests
cd frontend && pnpm build # type-check (vue-tsc) + build del frontendgofmty los tests son obligatorios antes de cerrar un cambio (verAGENTS.md).- No valides frontend ↔ backend con
wails dev: en modo dev el puentewindow.gopuede quedar sin definir y todas las llamadas al backend fallan (TypeError: Cannot read properties of undefined (reading 'main')). Es un quirk del proxy de Vite de Wails, no un bug de la app. Para probar el comportamiento real usa el build de producción.
| Ruta | Qué hay |
|---|---|
main.go / app.go / buildinfo.go |
Entry point de Wails, tray, wiring de módulos, ventana y versión/build |
internal/shell |
Tray, ciclo de vida del panel, ajustes, auto-inicio, i18n |
internal/servicecontrol |
Estado y control del servicio de OpenCode |
internal/webaccess |
Modos de acceso, URLs y credenciales |
internal/usage |
Consumo de OpenCode Go, token y tooltip |
internal/configviewer |
MCP / skills / agents y JSON de configuración |
internal/notifications |
Lógica de alertas (envío deshabilitado) |
frontend/ |
UI Vue 3 (components/ por sección, lib/ caché y ajustes, i18n es/en) |
brand/ |
Fuentes SVG de los iconos (icon.svg tile de app, mark.svg glifo) |
build/ |
Iconos y recursos por plataforma (build/bin es gitignored) |
scripts/ |
build-linux.sh, build-deb.sh, build-installer.ps1 (Windows), generate-icons.sh |
internal/cli |
Resolución del CLI de OpenCode (PATH, ~/.opencode/bin, etc.) |
La fuente única es brand/:
brand/icon.svg→ tile de app (#1E293B+ glifo>_verde).brand/mark.svg→ solo el glifo, concurrentColor(bandeja).
El símbolo es un prompt de terminal (>_): tile oscuro para la app y el .exe, y tile verde sólido con glifo oscuro para la bandeja (se distingue en barras claras y oscuras).
./scripts/generate-icons.sh rasteriza con Chrome headless y ensambla el ICO con Pillow. Los archivos generados se commitean y no se editan a mano:
| Archivo | Tamaño | Uso |
|---|---|---|
build/appicon.png |
1024 | máster de Wails |
build/windows/icon.ico |
16–256 | .exe e instalador (tile oscuro) |
build/windows/tray.ico |
16–256 | bandeja de Windows (tile verde sólido) |
build/linux/icon.png |
64 | bandeja en Linux/macOS (PNG embebido) |
build/linux/icon-256.png |
256 | menú de aplicaciones y .deb |
Si cambiás un SVG, corré el script antes de compilar: build/linux/icon.png y build/windows/tray.ico se embeben en el binario. go test ./... valida tamaños y formato de los iconos.
En Windows, Explorer puede conservar el icono viejo en caché. Si después de recompilar sigue apareciendo la “W”, ejecutá ie4uinit.exe -show o reinstalá la app.
- Fuente única:
Info.productVersiondewails.json. Alimenta los metadatos del.exe, el instalador, el.deby la tarjeta Ajustes → Acerca de. - El binario embebe
wails.json, así que unwails builddirecto también muestra la versión correcta (sin pasar por los scripts). - El commit, la fecha y la marca de cambios sin commitear se inyectan con
-ldflagsdesdescripts/build-linux.shyscripts/build-installer.ps1(Wails compila con-buildvcs=false). Si compilás sin esos scripts, la UI muestra “No disponible” en compilación y fecha, pero la versión sigue siendo la dewails.json. - Para publicar una versión: actualizá
Info.productVersion, sincronizáRELEASE.mdy recompilá. La app reporta ese valor automáticamente.
- Go 1.25+ y Wails CLI v2.16+.
pnpmpara el frontend.- Inno Setup 6.3+ solo si vas a generar el instalador.
- WebView2 Runtime (Windows 10/11 moderno ya lo incluye).
Con winget:
winget install --id JRSoftware.InnoSetup -eCon Chocolatey:
choco install innosetup -yO descargando el instalador desde https://jrsoftware.org/isinfo.php.
Comprueba que ISCC.exe está disponible con iscc /?. Si no se reconoce, añade al PATH una de estas carpetas:
C:\Program Files (x86)\Inno Setup 6
%LOCALAPPDATA%\Programs\Inno Setup 6
El script también busca ISCC.exe en esas rutas aunque no esté en el PATH.
# 1) .exe portable
wails build -clean -webview2 download
# 2) portable + instalador per-user
powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1
# 3) forzando una versión concreta
powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1 -Version 1.4.0El script:
- Lee
Info.productVersiondewails.json(o usa-Version). - Avisa si
opencode-tray.exeestá en ejecución. - Ejecuta
wails build -clean -webview2 download. - Ejecuta
ISCC.execonbuild\windows\installer\opencode-tray.iss.
También puedes compilar el instalador a mano:
iscc /DMyAppVersion=1.4.0 build\windows\installer\opencode-tray.issLa versión del .exe sale de Info.productVersion en wails.json; mantén ese valor y -Version sincronizados.
build/bin/opencode-tray.exe
build/bin/OpenCodeTray-Setup-<versión>.exe
Ambos están bajo build/bin/, que está en .gitignore: no se commitean. Sí se commitean la definición build/windows/installer/opencode-tray.iss y el script scripts/build-installer.ps1.
- Doble clic en
OpenCodeTray-Setup-<versión>.exe. - Instalación por usuario, sin UAC ni permisos de administrador.
- Directorio:
%LOCALAPPDATA%\Programs\OpenCode Tray. - Si falta WebView2, ofrece descargar e instalar el bootstrapper oficial de Microsoft (requiere Internet; si falla, muestra el enlace manual).
- Si
opencodeno está en elPATH, avisa pero no bloquea la instalación. - Accesos directos opcionales (escritorio y ejecutar al terminar).
- El instalador no crea una entrada de auto-inicio: eso lo controla la app desde Ajustes (
HKCU\...\Run). - Los ajustes (
%APPDATA%\OpenCodeTray\settings.json) se conservan al desinstalar.
Desde Configuración → Aplicaciones → OpenCode Tray, o ejecutando:
%LOCALAPPDATA%\Programs\OpenCode Tray\unins000.exe
Sin certificado, Windows SmartScreen puede mostrar una advertencia. Si tienes certificado, firma el .exe portable y el instalador con signtool antes de publicarlos. Inno Setup permite integrar la firma con SignTool en el .iss o pasarla por línea de comandos con /S<nombre>=<comando>.
-
go test ./...,pnpm testypnpm builden verde. -
Info.productVersionenwails.jsonactualizado yRELEASE.mdsincronizado. - Ajustes → Acerca de muestra la versión nueva (y commit/fecha si se compiló con los scripts).
-
./scripts/generate-icons.shejecutado si cambióbrand/(y assets commiteados). -
wails build -clean -webview2 downloadgenera el portable. -
scripts/build-installer.ps1genera el instalador. - Probar en una VM Windows limpia, sin Go/Wails instalados.
- Probar instalación con y sin WebView2, y con y sin
opencodeen PATH. - Verificar accesos directos, ejecución, desinstalación y conservación de ajustes.
- Publicar el portable y el instalador (nunca
build/bindentro de git).
Se puede compilar y ejecutar sin instalar o generar un
.debpara usarla como cualquier app del escritorio. La distribución oficial sigue siendo el.exede Windows.
sudo apt install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
export PATH="$HOME/go/bin:$PATH"CGO_ENABLED=1(Wails usa cgo en Linux; el script lo fuerza).- WebKitGTK 4.1 (
webkit2_41): Ubuntu 24.04+ ya no empaqueta WebKitGTK 4.0.
./scripts/build-linux.sh # wails build -clean -tags webkit2_41
./build/bin/opencode-tray # arranca con el icono del trayEl binario queda en build/bin/opencode-tray (gitignored). Para recompilar tras un cambio basta con repetir el script (build incremental ~10 s).
./scripts/build-deb.sh # → dist/opencode-tray_<versión>_amd64.deb
sudo apt install ./dist/opencode-tray_1.4.0_amd64.debEl paquete instala tres cosas:
| Ruta | Para qué |
|---|---|
/usr/bin/opencode-tray |
Ejecutable |
/usr/share/applications/opencode-tray.desktop |
Icono en el menú de aplicaciones (buscable como “OpenCode Tray”) |
/usr/share/icons/hicolor/256x256/apps/opencode-tray.png |
Icono del menú y del dock |
- Se lanza desde el menú de aplicaciones o con
opencode-trayen la terminal; no hace falta abrir una terminal para usarla. - El lanzador del menú abre el panel directamente (
--show-panel); si la app ya está corriendo, la segunda ejecución pide al proceso vivo que muestre el panel y termina (instancia única). - El auto-inicio (Ajustes → “Iniciar con el sistema”) arranca oculta, solo con el icono del tray.
- No necesita symlink ni tocar el
PATH: la app resuelve el CLI de OpenCode sola ($OPENCODE_BIN,PATH,~/.opencode/bin,~/.local/bin,/usr/local/bin,/usr/bin,/snap/bin). - La versión del paquete sale de
Info.productVersionenwails.json.
Desinstalar (los ajustes de ~/.config/OpenCodeTray se conservan):
sudo apt remove opencode-tray- Icono de bandeja: se embebe
build/linux/icon.png(64 px, tile verde) porque la bandeja decodifica PNG/JPEG y no ICO. Windows usa su propiobuild/windows/tray.ico(tile verde multi-tamaño); el.exey el instalador siguen usandobuild/windows/icon.ico(tile oscuro). - Panel: aparece centrado en el monitor principal y se puede arrastrar desde la franja superior (en Windows va anclado al icono del tray y no se mueve). Se centra solo la primera vez: conserva la posición que elijas. Bajo Wayland el compositor decide la posición inicial.
- Arranque oculto: Wails ignora
StartHiddenen Linux; la app oculta la ventana enstartuppara arrancar solo con el icono. - Clic en el icono: en GNOME/AppIndicator el clic abre el menú (el escritorio nunca emite
Activate), así que el panel se abre con Mostrar panel, la primera entrada del menú. En KDE/XFCE el clic izquierdo sí abre el panel. - Auto-inicio: crea
~/.config/autostart/opencode-tray.desktop(XDG). - Tooltip: GNOME no dibuja el tooltip del icono; por eso la primera fila del menú muestra el consumo y el reinicio (se actualiza solo). En Windows/KDE el tooltip nativo sigue funcionando.
- Secretos: sin DPAPI, el token manual de OpenCode Go se guarda en base64 (no cifrado). No lo uses en máquinas compartidas.
- Instancia única: implementada con
flock+ socket en$XDG_RUNTIME_DIR; una segunda ejecución pide mostrar el panel y sale. - Notificaciones: dependen del daemon de notificaciones del escritorio (el envío está deshabilitado en runtime, igual que en Windows).
-
Flyout: no hay preview visual al pasar el cursor (solo tooltip nativo) y no se puede redimensionar. En Windows tampoco se arrastra (va anclado al tray); en Linux sí, desde la franja superior.
-
Notificaciones: el envío de toasts está deshabilitado en runtime — el mecanismo de Wails entraba en conflicto con el bucle de la bandeja y la dejaba muda. La lógica (ritmo, umbrales, servicio detenido) está implementada y probada; detalle y cómo reactivarlo en
specs/SPEC-notifications.md. -
Fuentes web: la UI carga IBM Plex Sans + JetBrains Mono desde Google Fonts (
display=swap); sin red degrada a las fuentes del sistema y la app sigue siendo funcional. -
Linux: sin anclaje real al icono (esquina inferior derecha; Wayland puede ignorarla) y sin cifrado DPAPI para el token manual. Detalle en
specs/SPEC-shell.md→ Iteraciones 10 y 11. -
wails dev: el puente frontend ↔ backend puede fallar en modo dev (ver Desarrollo). Para validar comportamiento real usa siempre el build de producción:./scripts/build-linux.sh # Linux → build/bin/opencode-tray wails build # Windows → build/bin/opencode-tray.exe
El proyecto sigue Spec-Driven Development (SDD): primero las specs, luego el plan y las tareas, y solo después la implementación.
| Documento | Contenido |
|---|---|
specs/CAPABILITY-MAP.md |
Mapa de módulos y orden de construcción |
specs/SPEC-*.md |
Una spec por módulo (fuente de verdad del qué) |
tasks/plan.md / tasks/todo.md |
Plan técnico y tareas (el cómo) |
design-system/opencode-tray/MASTER.md |
Sistema de diseño (paleta, tipografía, a11y) |
RELEASE.md |
Notas de release y checklist de publicación |
AGENTS.md |
Reglas de trabajo, comandos y gotchas técnicos |