status-agent de Zenovay

zenovay status-agent es un daemon en segundo plano que mantiene un resumen en vivo de Zenovay — visitantes activos, MRR, tasa de errores — en tu barra de estado de tmux, y opcionalmente dispara notificaciones de escritorio cuando se cumplen reglas de umbral. Es el "panel siempre activo" para ingenieros que viven en la terminal.

status-agent es una funcionalidad para usuarios avanzados. Los mismos datos están disponibles vía zenovay live y el panel en app.zenovay.com. Usa status-agent cuando quieras una vista pasiva y ambiental que viva donde vive tu terminal.

Inicio rápido

# Inicia el daemon — hace polling cada 60s, escribe ~/.zenovay/tmux-status
zenovay status-agent --daemonize

# Conéctalo a tmux (~/.tmux.conf)
zenovay status-agent --install-tmux  # imprime la línea de conf; cópiala y recarga tmux

# Detener
zenovay status-agent --stop

Tras iniciar el daemon, tu barra de estado de tmux muestra algo como:

● 142 live  ▲ MRR $48.7k  ✗ 3 err/s  14:02

Cada segmento está coloreado — verde para visitantes en vivo, ámbar para MRR, rojo para errores. Cuando se cruza un umbral, todo el segmento se renderiza brevemente en vídeo invertido durante 30 segundos como pista visual junto con la notificación de escritorio.

Reglas de umbral

Pasa --notify-on con reglas separadas por comas en formato key>value o key<value:

zenovay status-agent --daemonize --notify-on "error_rate>5,revenue_drop>20"

Claves soportadas:

Las reglas disparan:

1. La notificación de escritorio nativa del SO (consulta plataformas de notificación)
2. El parpadeo de 30 segundos en vídeo invertido en el segmento de la barra de estado de tmux

Para evitar spam de notificaciones, la misma regla + bucket de valor se limita a una alerta cada 5 minutos. Así, un "error_rate>5" sostenido no dispara 60 veces en una hora — una vez cuando se activa por primera vez, luego silenciado hasta que el valor cruce un bucket diferente.

Configuración persistente

--save-config escribe los flags de la invocación actual en ~/.config/zenovay/config.json para que no tengas que repetirlos:

# Guarda una vez
zenovay status-agent --notify-on "error_rate>5" --interval-ms 30000 --save-config

# Todas las invocaciones posteriores recogen la config guardada
zenovay status-agent --daemonize   # usa error_rate>5 + 30000ms automáticamente

Inspecciona la config guardada:

zenovay status-agent --show-config
# {
#   "refreshIntervalMs": 30000,
#   "notifyOn": "error_rate>5",
#   "notifierPlatform": "auto"
# }

Los flags del CLI siempre sobrescriben la config guardada para una invocación concreta.

Auto-arranque al inicio

macOS — launchd

zenovay status-agent --install-launchd > ~/Library/LaunchAgents/com.zenovay.status-agent.plist
launchctl load ~/Library/LaunchAgents/com.zenovay.status-agent.plist

Linux — servicio de usuario systemd

mkdir -p ~/.config/systemd/user
zenovay status-agent --install-systemd > ~/.config/systemd/user/zenovay-status-agent.service
systemctl --user enable --now zenovay-status-agent

Windows

Por ahora no hay helper de auto-arranque; usa el Programador de tareas manualmente o ejecútalo desde una sesión de shell de autostart.

Plataformas de notificación

El daemon detecta tu plataforma y usa el mejor notificador nativo disponible, con un fallback universal:

OSC 9 es una secuencia de escape de terminal que funciona en iTerm2, WezTerm, Windows Terminal, Konsole y la mayoría de las terminales modernas — no requiere instalación adicional. Los notificadores nativos te dan toasts a nivel de SO que sobreviven al cierre de la ventana de la terminal; OSC 9 solo dispara mientras la terminal está en foco.

Si el notificador nativo no está instalado, el daemon recurre silenciosamente a OSC 9 — sin errores, sin notificaciones omitidas.

Ubicaciones de archivos

Ciclo de vida

--daemonize hace fork de un proceso hijo desacoplado y retorna de inmediato. Las invocaciones posteriores de --daemonize se niegan a iniciar un segundo daemon (causaría que dos procesos peleen por el archivo de estado):

$ zenovay status-agent --daemonize
status-agent: already running (PID 12345). Use --stop first.

--stop lee el archivo PID, envía SIGTERM y elimina el archivo. Incluye una comprobación de actividad para evitar enviar SIGTERM a un PID reciclado:

$ zenovay status-agent --stop
Stopped (PID: 12345)

La parada es inmediata — el polling loop del daemon despierta del sleep al recibir SIGTERM en lugar de esperar hasta 60 segundos al siguiente tick. Así las actualizaciones de la barra de estado de tmux se detienen en milisegundos tras retornar --stop.

Eventos de telemetría

El daemon emite 4 eventos de telemetría (sujetos a tu preferencia de opt-out vía zenovay telemetry):

Estos nos ayudan a entender qué umbrales configuran realmente los usuarios y si vale la pena seguir invirtiendo en la funcionalidad. No se envían IDs de sitio, códigos de tracking ni valores reales de métricas — solo claves de regla + buckets.

Solución de problemas

"no PID file — daemon not running?"

--stop se ejecutó sin un daemon activo. Es idempotente — seguro de re-ejecutar.

La barra de estado no muestra nada

Comprueba si el archivo se está escribiendo:

cat ~/.zenovay/tmux-status
# Debería mostrar: #[fg=colour141]● ...

Si el archivo está vacío o falta, el daemon no está corriendo. Ejecuta zenovay status-agent --daemonize para iniciarlo. Si el archivo SÍ está poblado pero tmux no lo muestra, te falta la línea de conf — zenovay status-agent --install-tmux la reimprime.

Notificaciones silenciosas

Si estás en macOS sin terminal-notifier instalado, OSC 9 solo dispara cuando la terminal de origen está en foco. brew install terminal-notifier para toasts a nivel de SO. Lo mismo en Linux: apt install libnotify-bin.

El daemon se cuelga / muere entre ticks

Comprueba ~/.zenovay/status-agent.pid tras unos minutos. Si ha desaparecido, el daemon murió. Ejecútalo en primer plano para ver stack traces: zenovay status-agent --child --interval-ms 5000.

Código fuente y feedback

El código fuente del CLI es privado del equipo de Zenovay; los binarios son públicos en npm + GitHub Releases + el tap de Homebrew. Los reportes de bugs y las solicitudes de funcionalidades son bienvenidos en community.zenovay.com.