Monitors

A monitor is a routine whose trigger is a watched source instead of a clock — poll a command or endpoint, wait for it to change, and fire an agent when it does. The daemon it shares with Schedule auto-starts on first add.

Three parts

Every monitor is a source, a condition, and an action:

• Source — --watch (shell command), --poll (re-run a command on an interval), --poll-http (GET a URL on an interval), --watch-file, --watch-device (a fleet box's load), or --on (a webhook, e.g. GitHub or Linear).
• Condition — --on-change (the default: fire when the observation differs from last time), --match <regex>, or --every.
• Action — --run <agent> --prompt, --routine, --notify, or --webhook-out. The fired event is injected into the prompt as {event}.

Poll a command, fire an agent

agents monitors add ci-red \
  --poll 'gh pr checks 1119 --json name,bucket' 30s --match 'fail' \
  --run claude --prompt 'CI failed on #1119: {event}. Diagnose and fix.' \
  --device yosemite-s0

--device pins the single owner machine that evaluates and fires the monitor — exactly-once, not once per box in the fleet.

Poll an endpoint, just notify

agents monitors add cert-issued \
  --poll-http 'https://secure.ssl.com/team/.../co-ec1l5dgjofa' 8h \
  --match 'issued' --notify --device zion

React to fleet load

agents monitors add box-loaded --watch-device yosemite-s0 --match loaded \
  --run claude --prompt 'yosemite-s0 is loaded: {event}. Investigate.'

Dry-run before it's live

agents monitors test ci-red   # evaluate the source once, print what would fire — no action taken

Manage

agents monitors list             # source, condition, action, owner, last fire
agents monitors view ci-red      # full YAML + current watched-state + recent fires
agents monitors logs ci-red      # latest action run's status + report
agents monitors runs ci-red      # fire history
agents monitors pause ci-red     # stop watching, keep the definition
agents monitors resume ci-red
agents monitors remove ci-red

v1 evaluates poll sources (command, HTTP, file, device). Push sources (--ws, webhook receivers) are accepted today and delivered through a receiver wired in a follow-up.

Related: Schedule — the clock-triggered sibling, same daemon, same secrets/skills/version layers. Secrets, Sessions.