Zenovay status-agent

zenovay status-agent is a background daemon that keeps a live Zenovay summary — active visitors, MRR, error rate — in your tmux status bar, and optionally fires desktop notifications when threshold rules trip. It's the "always-on dashboard" for engineers who live in the terminal.

Status-agent is a power-user feature. The same data is available via zenovay live and the dashboard at app.zenovay.com. Use status-agent when you want a passive, ambient view that lives wherever your terminal lives.

Quick start

# Start the daemon — polls every 60s, writes ~/.zenovay/tmux-status
zenovay status-agent --daemonize

# Wire it into tmux (~/.tmux.conf)
zenovay status-agent --install-tmux  # prints the conf line; copy + reload tmux

# Stop
zenovay status-agent --stop

After starting the daemon, your tmux status bar shows something like:

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

Each segment is colored — green for live visitors, amber for MRR, red for errors. When a threshold breaches, the whole segment briefly renders in reverse video for 30 seconds as a visual cue alongside the desktop notification.

Threshold rules

Pass --notify-on with comma-separated key>value or key<value rules:

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

Supported keys:

Rules trigger:

1. The OS-native desktop notification (see notification platforms)
2. The 30-second reverse-video flash in the tmux status segment

To prevent notification spam, the same rule + value bucket is rate-limited to one alert per 5 minutes. So a sustained "error_rate>5" doesn't fire 60 times in an hour — once when it first trips, then silenced until the value crosses a different bucket.

Persistent config

--save-config writes the current invocation's flags to ~/.config/zenovay/config.json so you don't have to repeat them:

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

# All subsequent invocations pick up the saved config
zenovay status-agent --daemonize   # uses error_rate>5 + 30000ms automatically

Inspect saved config:

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

CLI flags always override saved config for a single invocation.

Auto-start on 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

Currently no auto-start helper; use Task Scheduler manually or run from an autostart shell session.

Notification platforms

The daemon detects your platform and uses the best native notifier available, with a universal fallback:

OSC 9 is a terminal escape sequence that works in iTerm2, WezTerm, Windows Terminal, Konsole, and most modern terminals — no extra install needed. Native notifiers give you OS-level toast notifications that survive a closed terminal window; OSC 9 only fires while the terminal is in focus.

If the native notifier isn't installed, the daemon falls back to OSC 9 silently — no errors, no skipped notifications.

File locations

Lifecycle

--daemonize forks a detached child process and returns immediately. Subsequent --daemonize invocations refuse to start a second daemon (would cause two processes fighting over the status file):

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

--stop reads the PID file, sends SIGTERM, and removes the file. Includes a liveness check to avoid SIGTERM-ing a recycled PID:

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

Stop is immediate — the daemon's polling loop wakes from sleep on SIGTERM rather than waiting up to 60 seconds for the next tick. So tmux status updates stop within milliseconds of --stop returning.

Telemetry events

The daemon emits 4 telemetry events (subject to your zenovay telemetry opt-out preference):

These help us understand which thresholds users actually configure + whether the feature is worth investing in further. No site IDs, tracking codes, or actual metric values are sent — only rule keys + buckets.

Troubleshooting

"no PID file — daemon not running?"

--stop ran with no daemon active. Idempotent — safe to re-run.

Status bar shows nothing

Check whether the file's being written:

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

If the file is empty or missing, the daemon isn't running. zenovay status-agent --daemonize to start. If the file IS populated but tmux isn't displaying it, you missed the conf line — zenovay status-agent --install-tmux reprints it.

Notifications silent

If you're on macOS without terminal-notifier installed, OSC 9 only fires when the originating terminal is focused. brew install terminal-notifier for OS-level toasts. Same on Linux: apt install libnotify-bin.

Daemon crashes / dies between ticks

Check ~/.zenovay/status-agent.pid after a few minutes. If it's gone, the daemon died. Run in foreground for stack traces: zenovay status-agent --child --interval-ms 5000.

Source and feedback

CLI source is private to the Zenovay team; binaries are public on npm + GitHub Releases + the Homebrew tap. Bug reports and feature requests are welcome at community.zenovay.com.