EZO Watcher

EZO Watcher

The open-source AI SRE for your project: monitoring your coding agent installs, proves and fixes.

Agentic LiveOps monitoring: self-hosted, MCP-native, no account, and every check proven to go red before it counts.

Live demo · Quickstart · How it works · The fix loop · What agents see · MCP · Hosting · Docs

npm i -g ezo-watcher

watcher init

No global install: npx -y ezo-watcher init

A health route that answers {"ok": true} proves the process is up. It stays green when the database is down, the queue is stuck or last night's cron job never ran.

EZO Watcher is an alert wall and a pager for one project, built to be set up by the agent that already works on the code. The agent reads the repo, picks the telemetry points that can actually go red, adds each one with the file and line it came from, and proves it: watcher doctor --live --prove pushes every source's own reading past its threshold and fails the install unless the check flips. {"ok": true, "live": true} is the only done.

When something breaks later, the same agent reads the incident, ships a fix and closes it with a recheck. The source decides when it is well again, not the agent.

[!TIP]

[Open the live demo](https://ezo-watcher-demo.pages.dev): a full wall with sample data. Acknowledge, silence, park and recheck incidents; your changes stay in your browser.

How it works

flowchart LR

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

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

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

1. Scan. watcher scan lists what the repo already exposes: readiness routes, cron entries, scheduled workflows, Sentry, Grafana, Netdata, published ports.
2. Add. The agent turns each signal into a source. Every source carries the assertion that changes when a dependency is down, plus --found-at file:line so an incident points straight back at the code.
3. Prove. watcher doctor --live --prove mutates each reading (a bad JSON answer, a missed heartbeat, a disk past its limit) and fails unless the check goes red.
4. Run. One process serves the wall, pages your phone and speaks MCP.
5. Fix. An incident hands the agent a fix brief. The agent ships the fix and recheck --wait closes the incident only when the source reads healthy.

Quickstart

Give this to your agent

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 users: after watcher skills install, run /reload-skills so the new skill is picked up in that session.

Or by hand

# 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

No global install: npx -y ezo-watcher runs any verb the same way (npx -y ezo-watcher init). Open http://127.0.0.1:7717 for the wall. watcher init writes .watcher/config.json (commit it), .watcher/.env and .watcher/data/ (gitignored), and picks a free port from 7717.

What it sets up

The fix loop

Once the Watcher is running, the prompt is one line:

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

The agent drives watcher status --brief for one line at session start, then get_fix_context (or watcher incident --fix-context) for the incident's own brief: the source and target config, the assertion that failed, the last good and last bad observation, and the command that re-runs the check. After the fix and a redeploy, verify_fix (or watcher recheck --wait) closes the incident with the attribution only when the source itself says it is well again. The full loop is watcher skills fix.

Brief the agent at every session start

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

It writes the SessionStart hook into the project's .claude/settings.json, so a session that opens finds the wall's state in one line without asking. --target codex writes the same instruction into AGENTS.md instead (watcher hooks uninstall takes it back out).

Page when the agent itself stops working

Add one heartbeat (its ping token is generated into .watcher/.env for you) and a Stop hook that pings it after every turn:

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'" } ] } ] } }

Any turn inside the grace keeps the heartbeat green; when the agent stops working for longer than that, HeartbeatDown pages. The || true keeps a stopped Watcher from blocking the agent's turn. (Claude Code hooks reference, read 2026-11-04.)

What agents see

An agent dials the Watcher through MCP (/mcp) or the CLI and reads plain text. The demo shows it live: acknowledge or park an incident and every answer below changes. Every incident sheet has the same view under What your agent sees.

At the start of every session, watcher hooks install runs watcher status --brief: one line per open incident, nothing on a quiet wall.

$ 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 --fix-context or the MCP tool get_fix_context

The first MCP call, watch_state, is the wall in one answer (excerpt):

{

"text": "3 firing; 2 unattended, 1 acknowledged, 0 silen