Zenovay status-agent

zenovay status-agent ist ein Hintergrund-Daemon, der eine Live-Zenovay-Übersicht — aktive Besucher, MRR, Fehlerrate — in Ihrer tmux-Statusleiste anzeigt und optional Desktop-Benachrichtigungen auslöst, sobald Schwellenwert-Regeln greifen. Es ist das „immer aktive Dashboard" für Engineers, die im Terminal leben.

Status-agent ist ein Power-User-Feature. Dieselben Daten sind über zenovay live und das Dashboard unter app.zenovay.com verfügbar. Verwenden Sie status-agent, wenn Sie einen passiven, ambienten Blick wünschen, der dort lebt, wo auch Ihr Terminal läuft.

Schnellstart

# Daemon starten — pollt alle 60s, schreibt ~/.zenovay/tmux-status
zenovay status-agent --daemonize

# In tmux einbinden (~/.tmux.conf)
zenovay status-agent --install-tmux  # gibt die conf-Zeile aus; kopieren + tmux neu laden

# Stoppen
zenovay status-agent --stop

Nach dem Start des Daemons zeigt Ihre tmux-Statusleiste etwa Folgendes:

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

Jedes Segment ist farbig — grün für Live-Besucher, gelb für MRR, rot für Fehler. Wenn ein Schwellenwert überschritten wird, erscheint das gesamte Segment für 30 Sekunden kurz in invertierter Darstellung als visuelles Signal — zusätzlich zur Desktop-Benachrichtigung.

Schwellenwert-Regeln

Übergeben Sie --notify-on mit kommagetrennten Regeln im Format key>value oder key<value:

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

Unterstützte Keys:

Regeln lösen aus:

1. Die OS-native Desktop-Benachrichtigung (siehe Notification-Plattformen)
2. Den 30-sekündigen Reverse-Video-Flash im tmux-Statussegment

Um Spam bei Benachrichtigungen zu verhindern, ist dieselbe Regel + derselbe Wertebucket auf eine Meldung pro 5 Minuten rate-limitiert. Ein dauerhaft ausgelöstes „error_rate>5" feuert also nicht 60-mal pro Stunde — einmal beim ersten Auslösen, danach Stille, bis der Wert in einen anderen Bucket wechselt.

Persistente Konfiguration

--save-config schreibt die Flags des aktuellen Aufrufs in ~/.config/zenovay/config.json, sodass Sie sie nicht jedes Mal wiederholen müssen:

# Einmal speichern
zenovay status-agent --notify-on "error_rate>5" --interval-ms 30000 --save-config

# Alle weiteren Aufrufe übernehmen die gespeicherte Konfiguration
zenovay status-agent --daemonize   # nutzt automatisch error_rate>5 + 30000ms

Gespeicherte Konfiguration anzeigen:

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

CLI-Flags überschreiben die gespeicherte Konfiguration immer für den jeweiligen Einzelaufruf.

Autostart beim 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

Aktuell kein Autostart-Helper; verwenden Sie den Task Scheduler manuell oder starten Sie aus einer Autostart-Shell-Sitzung heraus.

Notification-Plattformen

Der Daemon erkennt Ihre Plattform und nutzt den besten verfügbaren nativen Notifier — mit einem universellen Fallback:

OSC 9 ist eine Terminal-Escape-Sequenz, die in iTerm2, WezTerm, Windows Terminal, Konsole und den meisten modernen Terminals funktioniert — keine zusätzliche Installation nötig. Native Notifier liefern Ihnen Toast-Benachrichtigungen auf OS-Ebene, die ein geschlossenes Terminalfenster überdauern; OSC 9 löst nur aus, solange das Terminal im Fokus ist.

Ist der native Notifier nicht installiert, fällt der Daemon stillschweigend auf OSC 9 zurück — keine Fehler, keine ausgelassenen Benachrichtigungen.

Dateipfade

Lebenszyklus

--daemonize forkt einen losgelösten Kindprozess und kehrt sofort zurück. Weitere --daemonize-Aufrufe verweigern den Start eines zweiten Daemons (würde dazu führen, dass zwei Prozesse um die Statusdatei kämpfen):

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

--stop liest die PID-Datei, sendet SIGTERM und entfernt die Datei. Inklusive Liveness-Check, damit nicht versehentlich eine wiederverwendete PID terminiert wird:

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

Stop wirkt sofort — der Polling-Loop des Daemons wacht bei SIGTERM aus dem Sleep auf und wartet nicht bis zu 60 Sekunden auf den nächsten Tick. tmux-Statusupdates stoppen also innerhalb von Millisekunden nach Rückkehr von --stop.

Telemetrie-Events

Der Daemon emittiert 4 Telemetrie-Events (vorbehaltlich Ihrer zenovay telemetry-Opt-out-Einstellung):

Diese helfen uns zu verstehen, welche Schwellenwerte Nutzer tatsächlich konfigurieren — und ob es sich lohnt, weiter in das Feature zu investieren. Es werden weder Site-IDs, Tracking-Codes noch tatsächliche Metrikwerte übertragen — nur Regel-Keys + Buckets.

Troubleshooting

„no PID file — daemon not running?"

--stop wurde ohne aktiven Daemon ausgeführt. Idempotent — kann sicher erneut ausgeführt werden.

Statusleiste zeigt nichts an

Prüfen Sie, ob die Datei beschrieben wird:

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

Ist die Datei leer oder fehlt sie, läuft der Daemon nicht. Mit zenovay status-agent --daemonize starten. Wenn die Datei zwar gefüllt ist, tmux sie aber nicht anzeigt, fehlt die conf-Zeile — zenovay status-agent --install-tmux gibt sie erneut aus.

Benachrichtigungen bleiben stumm

Wenn Sie unter macOS sind und terminal-notifier nicht installiert haben, löst OSC 9 nur aus, solange das auslösende Terminal fokussiert ist. brew install terminal-notifier für Toasts auf OS-Ebene. Auf Linux analog: apt install libnotify-bin.

Daemon stürzt ab / stirbt zwischen Ticks

Prüfen Sie nach einigen Minuten ~/.zenovay/status-agent.pid. Ist die Datei verschwunden, ist der Daemon abgestürzt. Im Vordergrund ausführen, um Stack Traces zu sehen: zenovay status-agent --child --interval-ms 5000.

Quellcode und Feedback

Der Quellcode des CLI ist privat für das Zenovay-Team; Binaries sind öffentlich auf npm + GitHub Releases + dem Homebrew-Tap. Bug Reports und Feature Requests sind unter community.zenovay.com willkommen.