Zenovay status-agent

zenovay status-agentは、Zenovayのライブサマリー（アクティブビジター、MRR、エラーレート）をtmuxステータスバーに常時表示し、必要に応じてしきい値ルールが発動した際にデスクトップ通知を発火するバックグラウンドデーモンです。ターミナルで生活するエンジニア向けの「常時稼働ダッシュボード」です。

status-agentはパワーユーザー向けの機能です。同じデータはzenovay liveやapp.zenovay.comのダッシュボードからも取得できます。ターミナルがある場所ならどこでも、受動的でアンビエントな表示が欲しいときにstatus-agentをご利用ください。

クイックスタート

# デーモンを起動 — 60秒ごとにポーリングし、~/.zenovay/tmux-statusへ書き込みます
zenovay status-agent --daemonize

# tmuxに組み込む（~/.tmux.conf）
zenovay status-agent --install-tmux  # confの行を出力します。コピーしてtmuxをリロード

# 停止
zenovay status-agent --stop

デーモンを起動すると、tmuxのステータスバーには次のように表示されます。

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

各セグメントには色がつきます — ライブビジターは緑、MRRはアンバー、エラーは赤です。しきい値違反が発生すると、デスクトップ通知と合わせて視覚的な合図として、該当のセグメント全体が30秒間反転表示で短時間レンダリングされます。

しきい値ルール

--notify-onにカンマ区切りでkey>valueまたはkey<valueのルールを渡します。

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

サポートされるキー:

ルールが発動すると以下が起きます。

1. OSネイティブのデスクトップ通知（通知プラットフォームを参照）
2. tmuxステータスセグメントでの30秒間の反転表示フラッシュ

通知のスパムを防ぐため、同じルールと値のバケットの組み合わせは5分あたり1アラートにレート制限されます。これにより、持続的なerror_rate>5が1時間に60回発火することはなく、最初に違反した1回だけ発火し、値が別のバケットに移るまでサイレンスされます。

永続的な設定

--save-configは現在の呼び出しのフラグを~/.config/zenovay/config.jsonに書き込みます。これにより毎回フラグを指定する必要がなくなります。

# 一度保存
zenovay status-agent --notify-on "error_rate>5" --interval-ms 30000 --save-config

# 以降の呼び出しは保存された設定を自動的に読み込みます
zenovay status-agent --daemonize   # error_rate>5 + 30000msが自動適用されます

保存された設定の確認:

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

CLIフラグは、その単一の呼び出しに対して常に保存された設定を上書きします。

起動時の自動開始

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ユーザーサービス

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

現時点では自動起動ヘルパーはありません。タスクスケジューラーを手動で利用するか、自動起動シェルセッションから実行してください。

通知プラットフォーム

デーモンはお使いのプラットフォームを検出し、利用可能な最良のネイティブ通知ツールを使用します。すべての環境で動作するフォールバックも備えています。

OSC 9はターミナルのエスケープシーケンスで、iTerm2、WezTerm、Windows Terminal、Konsole、その他多くのモダンなターミナルで動作します — 追加のインストールは不要です。ネイティブ通知ツールを使うと、ターミナルウィンドウを閉じても残るOSレベルのトースト通知が得られます。OSC 9はターミナルがフォーカスされているときにのみ発火します。

ネイティブの通知ツールがインストールされていない場合、デーモンはサイレントにOSC 9へフォールバックします — エラーも通知のスキップもありません。

ファイルの場所

ライフサイクル

--daemonizeは切り離された子プロセスをforkして即座に戻ります。後続の--daemonize呼び出しは2つ目のデーモンの起動を拒否します（2つのプロセスがステータスファイルを取り合うことを避けるため）。

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

--stopはPIDファイルを読み、SIGTERMを送り、ファイルを削除します。リサイクルされたPIDにSIGTERMを送らないように、生存確認も含まれています。

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

停止は即座に行われます — デーモンのポーリングループは、次のtickまで最大60秒待たずに、SIGTERMを受け取った時点でスリープから目覚めます。そのため、--stopが戻ってからミリ秒以内にtmuxのステータス更新は止まります。

テレメトリイベント

デーモンは4つのテレメトリイベントを送信します（zenovay telemetryのオプトアウト設定に従います）。

これらは、ユーザーが実際にどのしきい値を設定しているか、そしてこの機能にさらに投資する価値があるかを把握するのに役立ちます。サイトID、トラッキングコード、実際のメトリック値は送信されません — ルールキーとバケットのみです。

トラブルシューティング

「no PID file — daemon not running?」

--stopがアクティブなデーモンなしで実行されました。冪等なので、再実行しても問題ありません。

ステータスバーに何も表示されない

ファイルが書き込まれているか確認します。

cat ~/.zenovay/tmux-status
# 次のような表示が出るはずです: #[fg=colour141]● ...

ファイルが空または存在しない場合、デーモンは実行されていません。zenovay status-agent --daemonizeで起動してください。ファイルは書き込まれているのにtmuxが表示しない場合は、confの行が抜けています — zenovay status-agent --install-tmuxで再表示できます。

通知が鳴らない

macOSでterminal-notifierがインストールされていない場合、OSC 9は発信元のターミナルがフォーカスされているときにのみ発火します。OSレベルのトーストを得るにはbrew install terminal-notifierを実行してください。Linuxでも同様で、apt install libnotify-binを実行します。

デーモンがクラッシュする／tickの間に落ちる

数分後に~/.zenovay/status-agent.pidを確認してください。なくなっていればデーモンが落ちています。スタックトレースを得るためにフォアグラウンドで実行します: zenovay status-agent --child --interval-ms 5000。

ソースとフィードバック

CLIのソースはZenovayチーム内で非公開ですが、バイナリはnpm、GitHub Releases、Homebrew tapで公開されています。バグ報告や機能リクエストはcommunity.zenovay.comまでお寄せください。