Zenovay status-agent

O zenovay status-agent é um daemon em background que mantém um resumo ao vivo do Zenovay — visitantes ativos, MRR, taxa de erros — na sua barra de status do tmux e, opcionalmente, dispara notificações de desktop quando regras de threshold são quebradas. É o "dashboard sempre ligado" para engenheiros que vivem no terminal.

O status-agent é um recurso para usuários avançados. Os mesmos dados estão disponíveis via zenovay live e no painel em app.zenovay.com. Use o status-agent quando quiser uma visão passiva e ambiente que vive onde quer que seu terminal esteja.

Início rápido

# Inicia o daemon — faz polling a cada 60s, escreve em ~/.zenovay/tmux-status
zenovay status-agent --daemonize

# Conecta ao tmux (~/.tmux.conf)
zenovay status-agent --install-tmux  # imprime a linha de conf; copie + recarregue o tmux

# Para
zenovay status-agent --stop

Depois de iniciar o daemon, sua barra de status do tmux mostra algo como:

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

Cada segmento é colorido — verde para visitantes ao vivo, âmbar para MRR, vermelho para erros. Quando um threshold é quebrado, o segmento inteiro é renderizado brevemente em vídeo invertido por 30 segundos, como dica visual junto com a notificação de desktop.

Regras de threshold

Passe --notify-on com regras separadas por vírgula no formato key>value ou key<value:

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

Chaves suportadas:

As regras disparam:

1. A notificação de desktop nativa do SO (veja plataformas de notificação)
2. O flash de vídeo invertido de 30 segundos no segmento de status do tmux

Para evitar spam de notificações, a mesma combinação regra + bucket de valor é limitada a um alerta a cada 5 minutos. Assim, um "error_rate>5" sustentado não dispara 60 vezes em uma hora — uma vez quando primeiro é quebrado, depois silenciado até o valor cruzar um bucket diferente.

Configuração persistente

O --save-config grava as flags da invocação atual em ~/.config/zenovay/config.json para que você não precise repeti-las:

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

# Todas as invocações seguintes pegam a config salva
zenovay status-agent --daemonize   # usa error_rate>5 + 30000ms automaticamente

Inspecionar a config salva:

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

As flags do CLI sempre sobrescrevem a config salva para uma única invocação.

Auto-início no boot

macOS — launchd

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

Linux — systemd user service

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

Atualmente não há helper de auto-início; use o Agendador de Tarefas manualmente ou execute a partir de uma sessão de shell de autostart.

Plataformas de notificação

O daemon detecta sua plataforma e usa o melhor notifier nativo disponível, com um fallback universal:

OSC 9 é uma sequência de escape de terminal que funciona em iTerm2, WezTerm, Windows Terminal, Konsole e na maioria dos terminais modernos — sem instalação extra. Os notifiers nativos entregam toasts no nível do SO que sobrevivem ao fechamento da janela do terminal; o OSC 9 só dispara enquanto o terminal está em foco.

Se o notifier nativo não estiver instalado, o daemon faz fallback para OSC 9 silenciosamente — sem erros, sem notificações puladas.

Locais de arquivo

Ciclo de vida

O --daemonize faz fork de um processo filho destacado e retorna imediatamente. Invocações subsequentes de --daemonize se recusam a iniciar um segundo daemon (causaria dois processos brigando pelo arquivo de status):

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

O --stop lê o arquivo PID, envia SIGTERM e remove o arquivo. Inclui uma verificação de liveness para evitar SIGTERM em um PID reciclado:

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

A parada é imediata — o polling loop do daemon acorda do sleep com SIGTERM em vez de esperar até 60 segundos pelo próximo tick. Ou seja, as atualizações de status do tmux param em milissegundos depois que o --stop retorna.

Eventos de telemetria

O daemon emite 4 eventos de telemetria (sujeitos à sua preferência de opt-out via zenovay telemetry):

Eles nos ajudam a entender quais thresholds os usuários efetivamente configuram e se vale a pena investir mais no recurso. Nenhum site ID, código de tracking ou valor real de métrica é enviado — apenas chaves de regra + buckets.

Solução de problemas

"no PID file — daemon not running?"

O --stop rodou sem nenhum daemon ativo. Idempotente — pode reexecutar com segurança.

A barra de status não mostra nada

Verifique se o arquivo está sendo escrito:

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

Se o arquivo estiver vazio ou ausente, o daemon não está rodando. Use zenovay status-agent --daemonize para iniciar. Se o arquivo ESTÁ populado mas o tmux não está exibindo, você pulou a linha de conf — zenovay status-agent --install-tmux reimprime ela.

Notificações silenciosas

Se você está no macOS sem o terminal-notifier instalado, o OSC 9 só dispara quando o terminal de origem está em foco. Use brew install terminal-notifier para toasts no nível do SO. Idem no Linux: apt install libnotify-bin.

O daemon trava / morre entre ticks

Verifique ~/.zenovay/status-agent.pid depois de alguns minutos. Se sumiu, o daemon morreu. Rode em foreground para ver stack traces: zenovay status-agent --child --interval-ms 5000.

Código-fonte e feedback

O código-fonte do CLI é privado da equipe Zenovay; os binários são públicos no npm + GitHub Releases + tap do Homebrew. Relatos de bugs e pedidos de funcionalidades são bem-vindos em community.zenovay.com.