EZO Watcher

EZO Watcher

プロジェクトのためのオープンソース AI SRE：コーディングエージェントのインストールを監視し、検証し、修正します。
エージェント型 LiveOps 監視：セルフホスト可能、MCP ネイティブ、アカウント不要。すべてのチェックは、カウント対象になる前に異常を検知できることが検証されます。

ライブデモ · クイックスタート · 仕組み · 修正ループ · エージェントに見える情報 · MCP · ホスティング · ドキュメント

npm i -g ezo-watcher
watcher init

グローバルインストールは不要です：npx -y ezo-watcher init

{"ok": true} を返すヘルスルートでわかるのは、プロセスが起動していることだけです。データベースが停止していても、キューが詰まっていても、昨夜の cron ジョブが実行されていなくても、正常を示す緑のままです。

EZO Watcher は、すでにコードに取り組んでいるエージェントがセットアップできるように作られた、単一プロジェクト向けのアラートウォール兼ページャーです。エージェントはリポジトリを読み、実際に異常を検知できるテレメトリーポイントを選び、各ポイントをその出所となるファイルと行番号とともに追加して、検証します。watcher doctor --live --prove は各ソース固有の値をしきい値の異常側まで変化させ、チェックが切り替わらなければインストールを失敗させます。完了とみなされるのは {"ok": true, "live": true} の場合だけです。

後で問題が発生したら、同じエージェントがインシデントを読み、修正を反映して、再チェックでクローズします。復旧したと判断するのはエージェントではなく、ソースです。

ヒント

ライブデモを開く：サンプルデータを使った完全なウォールです。インシデントの確認、通知の一時停止、保留、再チェックを試せます。変更内容はブラウザーに保存されます。

仕組み

flowchart LR
    subgraph project["Your project"]
        code["Code, cron, configs"]
        app["Running app"]
    end

    agent(["Coding agent"])
    cfg[".watcher/config.json<br/>checks as code"]
    server["Watcher server<br/>one Node process + SQLite"]
    wall["Alert wall"]
    phone["Phone<br/>ntfy · push · SMS · email"]

    agent -- "watcher scan" --> code
    agent -- "watcher add --found-at" --> cfg
    cfg --> server
    server -- "probes · heartbeats<br/>webhooks · host" --> app
    server --> wall
    server --> phone
    server -- "MCP · CLI · hooks" --> agent
    agent -- "fix, then recheck --wait" --> app

1. スキャン。 watcher scan は、リポジトリで現在公開されているものを一覧表示します。レディネスルート、cron エントリー、スケジュールされたワークフロー、Sentry、Grafana、Netdata、公開ポートなどが対象です。
2. 追加。 エージェントは各シグナルをソースに変換します。各ソースには、依存先が停止したときに変化するアサーションと、インシデントからコードに直接たどれるようにする --found-at file:line が含まれます。
3. 検証。 watcher doctor --live --prove は各値を変化させ（不正な JSON の応答、ハートビートの欠落、上限を超えたディスク容量など）、チェックが異常を示さなければ失敗します。
4. 実行。 1 つのプロセスがウォールを配信し、スマートフォンにページを送り、MCP で通信します。
5. 修正。 インシデントはエージェントに修正概要を渡します。エージェントが修正を反映し、ソースが正常と判定した場合に限り、recheck --wait がインシデントをクローズします。

エージェントに渡す

Set up EZO Watcher for this project. Install the CLI with
`CI=1 npm_config_yes=true npm i -g ezo-watcher`, then run
`watcher init` and `watcher skills install --target all`, and follow the
ezo-watcher skill end to end (read `.claude/skills/ezo-watcher/SKILL.md` or
`.agents/skills/ezo-watcher/SKILL.md` if the skill is not listed in this session yet).

Follow its ranking: a dependency-gated readiness route first (never a route that
just returns {"ok": true}), a heartbeat for every scheduled job, then any Sentry,
Grafana or Netdata already in the project. Add one alert channel and prove it
with `watcher test-alert`.

Do not stop until `watcher doctor --live --prove --json` prints
{"ok": true, "live": true}. If this project has no server and no scheduled job,
add `watcher add host --id host` — the machine itself, read locally with nothing
installed (load, memory, free space, optionally a pid file) — and prove it. Only
if there is no server, no scheduled job and no host to watch either, run
`watcher doctor --no-runtime-surface --json` and tell me instead; a configured
source always wins over `--no-runtime-surface`. Ask me only
for the credential a chosen source or channel needs, and tell me what you watched
and what you skipped.

Claude Code ユーザー：watcher skills install の実行後、新しいスキルをそのセッションで読み込むために /reload-skills を実行してください。

または手動で設定する

# Node 24+.
npm i -g ezo-watcher
watcher --version

cd my-project
watcher init
watcher scan --json
watcher add http-probe --id app --url http://127.0.0.1:3000/readyz \
  --expect-json '{"db.ok":true}' --found-at src/server.ts:42 \
  --read "readiness reads the database"
watcher add channel ntfy --id ntfy --server https://ntfy.sh --topic-env WATCHER_NTFY_TOPIC
# or, with no credential at all: watcher add channel file --id local
watcher run --detach
watcher doctor --live --prove --json    # {"ok": true, "live": true}
watcher test-alert

グローバルインストールは不要です。npx -y ezo-watcher <verb> を実行すれば、どの verb も同じように使えます（npx -y ezo-watcher init）。ウォールを開くには http://127.0.0.1:7717 にアクセスしてください。watcher init は .watcher/config.json（コミットしてください）、.watcher/.env と .watcher/data/（gitignore 対象）を書き込み、7717 から空いているポートを選びます。

セットアップされる内容

修正ループ

Watcher の実行後、プロンプトは 1 行です。

Check the Watcher for open incidents and fix them; verify each fix with a recheck.

sequenceDiagram
    autonumber
    participant S as Source
    participant W as Watcher
    participant P as Phone
    participant A as Agent
    S->>W: readiness answers {"db": {"ok": false}}
    W->>P: page: Checkout api is down
    A->>W: watcher status --brief (session start)
    A->>W: get_fix_context
    W-->>A: failed assertion, last good and bad reading, found-at server.mjs:35
    A->>A: fix the code, redeploy
    A->>W: verify_fix / recheck --wait
    W->>S: re-run the check now
    S-->>W: {"db": {"ok": true}}
    W-->>A: resolved, confirmed by the source

エージェントはセッション開始時に watcher status --brief を実行し、1 行の状態を確認します。次に get_fix_context（または watcher incident <key> --fix-context）を使い、インシデント固有の概要を取得します。概要にはソースとターゲットの設定、失敗した検証、最後に正常だった観測と最後に異常だった観測、チェックを再実行するコマンドが含まれます。修正して再デプロイした後、verify_fix（または watcher recheck <key> --wait）を実行すると、ソース自体が再び正常だと示した場合に限り、修正の帰属情報を付けてインシデントをクローズします。完全なループは watcher skills fix です。

watcher hooks install --target claude     # SessionStart: watcher status --brief

watcher add heartbeat --id agent-session --every 30m --grace 15m \
  --token-env WATCHER_AGENT_SESSION_TOKEN

{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command",
          "command": "sh -c 'set -a; . .watcher/.env 2>/dev/null; curl -fsS -X POST -H \"Authorization: Bearer $WATCHER_AGENT_SESSION_TOKEN\" http://127.0.0.1:7717/ingest/heartbeat/agent-session >/dev/null 2>&1 || true'" }
      ] }
    ]
  }
}

エージェントは、MCP（/mcp）または CLI を介して Watcher に接続し、プレーンテキストを読み取ります。デモでは、実際の動作を確認できます。インシデントを確認または保留にすると、以下の各回答がすべて変化します。すべてのインシデントシートで、エージェントに見えるものの下に同じ表示を確認できます。

セッションの開始時に毎回、watcher hooks install が watcher status --brief を実行します。オープン中のインシデントごとに1行ずつ表示し、問題がないときは何も表示しません。

$ watcher status --brief
warning  Billing jobs  HeartbeatDown  50m  Billing jobs|HeartbeatDown
page  Checkout API  ProbeDown  21m  Checkout API|ProbeDown
warning  Worker hosts  HostDiskFree  2h  Worker hosts|HostDiskFree
run `watcher incident <key> --fix-context` or the MCP tool get_fix_context

最初の MCP 呼び出し watch_state では、壁全体が1つの回答として表示されます（抜粋）：

{
 "text": "3 firing; 2 unattended, 1 acknowledged, 0 silenced; 1 page, 2 warning, 0 info; 1 parked (not live: an open verdict that is not due yet). Every source is answering.",
 "counts": { "firing": 3, "unattended": 2, "acknowledged": 1, "silenced": 0, "parked": 1, "page": 1, "warning": 2, "info": 0 }
}

次に get_fix_context {"key":"Checkout API|ProbeDown"}（または watcher incident 'Checkout API|ProbeDown' --fix-context --json）を呼び出すと、人に尋ねることなく修正に必要な情報がすべて返されます（ここでは省略しています。実際の概要は約200行です）：

{
 "key": "Checkout API|ProbeDown",
 "summary": "checkout-api is down: HTTP 503 in 3023ms, expected 200",
 "state": { "firing": true, "attention": "none", "ackedBy": null, "silencedUntil": null, "parkedState": null, "parkedUntil": null },
 // sources[0].target: the config that failed
 "target": { "id": "checkout-api", "url": "https://api.acme.example/checkout/readyz", "expectJson": { "ok": true, "db.ok": true }, "slowMs": 800 },
 "asserts": [{ "asserts": ["status 200", "body.ok = true", "body.db.ok = true"], "failed": ["status 200"],
   "failureDetail": "HTTP 503 in 3023ms, expected 200 (25 failed polls in a row)" }],
 "observations": {
  "lastGood": { "at": "2026-11-05T15:06:00.000Z", "status": 200, "body": "{\"ok\":true,\"db\":{\"ok\":true,\"poolInUse\":8}}" },
  "lastBad": { "at": "2026-11-05T15:30:00.000Z", "status": 503, "detail": "HTTP 503 in 3023ms, expected 200" }
 },
 "reproduce": {
  "command": "curl -sS -m 10 'https://api.acme.example/checkout/readyz' | jq '.ok'", "expect": "true",
  "watcher": "watcher recheck 'Checkout API|ProbeDown' --wait --json"
 },
 "next": [{ "action": "fix" }, { "action": "restart-or-deploy" }, { "action": "verify" }]  // each with its detail
}

壁

インシデントを開くとシートが表示されます。何が失敗したか、証拠、履歴、送信されたすべての通知を確認できます。	スマートフォンでも同じ壁を表示できます。Web プッシュ対応の PWA としてインストールできます。

発生中のタイルが画面を占め、正常なサービスは密度の高いグリッドに縮小されます。ページは赤、警告は琥珀色、確認済みのインシデントには対応者が表示され、保留中のインシデントには専用の色が付き、個別に期限切れになります。表示デザインは ISA-101 の高性能 HMI の実践に従い、通常はグレー、注意が必要な対象にのみ色を使います（docs/design.md）。

MCP

2つの形式があり、まずは stdio です：

watcher mcp-config --client claude     # also: cursor, codex; --show-secret prints the token

stdio 形式では、実行中の CLI 自体（node <the install's bin/watcher.mjs> mcp --dir <project>）を登録します。クライアントはプロジェクト内で小さなブリッジを起動し、ブリッジが .watcher/.env から WATCHER_MCP_TOKEN を読み取るため、登録情報にシークレットは含まれません。Watcher と同じマシン上のエージェントには、この形式を使用してください。

HTTP 形式では、実行中のサーバー独自のエンドポイント <baseUrl>/mcp（ステートレスな Streamable HTTP）を、Authorization: Bearer $WATCHER_MCP_TOKEN の背後で使用します。同じエージェントがトンネルの届く場所ならどこからでも作業できるようにするには、Tunnel の背後で使用してください。Access が有効な場合は、/mcp に Cloudflare Access のバイパスを設定してください（エンドポイントは独自のベアラートークンを引き続き使用します。watcher skills cloudflare を参照）。

すべての入力は docs/mcp.md に記載されています。

異なる点

• ステータスではなく、アサーションで証明します。 200 はソケットが接続を受け付けたことを示すだけです。各チェックに、変更を加えると結果が反転する述語（--prove）が含まれて初めて、インストールは正常と判定されます。そのため、データベースの故障、キューの停止、ジョブの停止を実際に検知できます。
• 沈黙を優先します。 手作業でラベル付けした 4 つのリポジトリを対象にしたプロトタイプのスキャンでは、ファイルスキャンで HTTP の表面の大部分は見つかりましたが、沈黙のうち見つかったのは約 5 分の 1 にすぎませんでした。インストールスクリプト内で生成されるスケジュール、実行時に作成される launchd/systemd ユニット、プルキューワーカー、製品独自の設定で定義される古さ、状態ディレクトリの書き込み可能性、コード定数として保持された依存関係の URL などです。このスキルにはそのチェックリストが含まれており、各項目はハートビートまたは期限切れウィンドウ付きの Webhook になります。
• ローカルで、アカウントは不要です。 Node プロセス 1 つ、node:sqlite、Git 内の設定、0600 の環境変数ファイルに保存したシークレットだけで動作します。登録は不要で、ノートパソコン、サーバー、または Cloudflare Tunnel の背後で実行できます。
• エージェントにネイティブ対応しています。 ドキュメントは CLI に同梱され（watcher skills <topic>）、インストールのループはエージェント向けに記述されています。また、実行中の Watcher は MCP に対応しているため、エージェントは自分自身としてウォールを読み取り、確認、コメント、ミュート、一時停止、再チェックを行えます。

ホスティング

flowchart LR
    local["Local process"] --> svc["launchd / systemd<br/>service"] --> vps["Docker or a VPS"] --> tunnel["Cloudflare Tunnel<br/>$0, no port forwarding"] --> containers["Cloudflare Containers<br/>beta"]

まずは最も安価な方法から。Cloudflare Tunnel は、「自分の Cloudflare キーでホストする」場合のデフォルトです。すでに所有しているゾーン上のホスト名を使い、ポートフォワーディングは不要です。watcher cloudflare tunnel --hostname watch.example.com でトンネル、DNS、実行トークンを設定できます。watcher cloudflare quick は、デモ用の一時的な公開 URL を提供します。Cloudflare Containers は起動したままにすると月額約 $9.57 かかり、LAN をプローブできません。Workers のエッジポートはまだ実装されていません。詳細は watcher skills hosting と watcher skills cloudflare をご覧ください。

ループバック以外にバインドするには WATCHER_ADMIN_TOKEN が必要です。設定されていない場合、サーバーは起動を拒否します。

ドキュメント

テレメトリ

CLI とサーバーは、問題を特定して優先的に修正できるよう、匿名の利用データ（動詞とフラグ名、終了コード、doctor のチェックコード、内部エラーの種類）を送信します。パス、ホスト、URL、設定値、環境変数の値は送信しません。一度限りの通知の後、テレメトリは有効になります。watcher telemetry disable または DO_NOT_TRACK=1 で無効にできます。WATCHER_TELEMETRY_DEBUG=1 を設定すると、送信される内容がそのまま出力されます。送信内容と送信先については、docs/telemetry.md をご覧ください。

ステータス

パブリックプレビュー版です。npm では ezo-watcher として公開されています。他者のプロジェクト向けにウォールをホストすることはサポートしていますが、マルチテナントホスティングには対応していません。

開発

npm ci
npm run build
npm run typecheck
npm test

Node 24 以降、ESM、TypeScript を使用します。ディレクトリ構成、テストルール、リークゲートについては AGENTS.md を、製品に関する判断については docs/design.md をご覧ください。

ライセンス

MIT © EZO Labs Inc.