--- name: agentmonitors-setup description: Set up Agent Monitors — a local-first, durable monitoring system for coding agents — end to end. Detect the host, install the CLI, author a monitor from the user's plain-language intent, and prove it actually delivers before declaring success. Use this when a user points you at this URL, or asks to "set up agent monitors", "enable monitoring here", "watch this file/API/command", "notify me when X changes", or "turn on agentmonitors". --- # Agent Monitors — agent setup guide You were handed this file directly (probably as `https://agentmonitors.io/skill.md`), with no other context. That's enough. This document is self-contained: follow it top to bottom and you can take a user from nothing installed to a monitor that has verifiably fired. ## What you're setting up Agent Monitors watches something the user cares about — a file, an HTTP endpoint, a command's output, a git ref, a schedule — with a small local daemon, and tells you (the agent) when it changes, at a good moment in your session. It is **local-first**: everything runs on the user's machine, nothing is sent to a cloud service. Delivery to you happens **entirely through your host's hook mechanism** — there is no separate service to sign up for. ## How to behave - **Do the work yourself.** Install the CLI, write the config files, run validation, and run the verification recipe below. Don't hand the user a list of commands to run themselves. - **Ask only for intent**, not configuration. "What do you want to watch, and what should I do when it changes?" is normally the only question you need. Infer the rest (source type, globs, urgency) from the answer using the tables below. - **Never make the user hand-edit YAML.** Scaffold with `agentmonitors init`, then edit the generated file yourself. - **Do not declare the monitor "set up" until you have demonstrated a delivered event.** A monitor that only parses and validates is unverified. Phase 5 below is not optional — it is the difference between "I wrote a config file" and "I proved your agent gets told." --- ## Phase 0 — Prerequisites: install the CLI Check whether the CLI is already on the user's `PATH`: ```bash agentmonitors --help ``` If that fails, install it: ```bash npm install -g agentmonitors ``` This installs the `agentmonitors` binary (a thin launcher over the published `@agentmonitors/cli` package — both resolve to the same CLI; `agentmonitors` is just the short name). Verify with `agentmonitors --help` again, or `npx agentmonitors --help` to try it without a global install. --- ## Phase 1 — Detect the host, then branch Figure out which of these three situations you're in before doing anything else. ### 1a. Claude Code, plugin install available (the common case) If you can run Claude Code slash commands, add the plugin marketplace and install the plugin: ```text /plugin marketplace add mike-north/AgentMonitors /plugin install agentmonitors@agentmonitors ``` This wires Claude Code's `SessionStart` / `UserPromptSubmit` / `SessionEnd` lifecycle hooks to the CLI automatically. Once a project is enabled (Phase 2), monitors just show up in sessions — you never run delivery commands by hand in normal use. Continue to Phase 2. ### 1b. Claude Code, hooks-only (MCP blocked / restricted-corporate) The plugin also ships an optional MCP "channel" for push-style delivery. If your organization blocks MCP servers or third-party plugin marketplaces by policy, that's fine — **delivery semantics are identical without it.** The channel is a second, additive transport for the same durable events; the hook-based transport below is the default for every environment and never depends on channels. If you can install the plugin (1a) but MCP is blocked, do that — the hooks still work; you only lose the optional real-time push, not delivery itself. If you cannot install any plugin at all, wire the hooks by hand in `.claude/settings.json` (or `.claude/settings.local.json` for a personal-only, gitignored setup) at the project root: ```json { "hooks": { "SessionStart": [ { "matcher": "", "hooks": [ { "type": "command", "command": "command -v agentmonitors >/dev/null 2>&1 && agentmonitors session start || true" } ] } ], "UserPromptSubmit": [ { "matcher": "", "hooks": [ { "type": "command", "command": "command -v agentmonitors >/dev/null 2>&1 && agentmonitors hook deliver || true" } ] } ], "SessionEnd": [ { "matcher": "", "hooks": [ { "type": "command", "command": "command -v agentmonitors >/dev/null 2>&1 && agentmonitors session end || true" } ] } ] } } ``` Each command is guarded (`command -v … && … || true`) so the host hook never reports a failure when the CLI is missing from `PATH` or exits non-zero — an unguarded failing hook would disrupt the user's session. This mirrors the guard the official plugin's own hook wiring uses. - `SessionStart` runs `agentmonitors session start`, which lazy-boots the per-project daemon and registers the session (and prints a recap of anything already pending). - `UserPromptSubmit` runs `agentmonitors hook deliver`, which claims and injects pending monitor context at each turn boundary. - `SessionEnd` runs `agentmonitors session end`, which deregisters the session so the idle daemon can reap itself. All three read the hook's JSON payload from **stdin** (Claude Code's standard hook input contract) — no extra flags needed. Continue to Phase 2. ### 1c. Codex or another host **Honest current state:** Agent Monitors' automatic in-session delivery is Claude-Code-specific today — there is no Codex (or other host) hook wiring shipped yet. What *does* work today, host-independently, is everything upstream of delivery: install the CLI, author and validate monitors, and run the daemon to observe changes and materialize durable events. You can still prove the underlying mechanism fires correctly using the CLI-only verification recipe in Phase 5 (it doesn't depend on any host-specific hook — it drives the same daemon/session/events surface directly). Say this plainly to the user rather than implying full parity with the Claude Code path: monitor authoring and CLI-level verification work today; automatic delivery into a live Codex/other session does not yet. --- ## Phase 2 — Enable the project Monitoring is off by default per project. Check whether your CLI has the one-shot bootstrap flag first — it's the newer, preferred path, but some installs predate it: ```bash agentmonitors init --help ``` **If `--enable-only` is listed**, use it. It creates the gitignored opt-in file and updates `.gitignore` for you, with no monitor and no prompts: ```bash agentmonitors init --enable-only ``` This creates `.claude/agentmonitors.local.md` (the per-developer opt-in file) and adds both `.claude/*.local.*` and `/.agentmonitors/` to `.gitignore` — no manual file-editing needed. Skip straight to Phase 3. **If `--enable-only` is not listed** (older CLI version), create an equivalent enable file by hand: ```bash mkdir -p .claude cat > .claude/agentmonitors.local.md <<'EOF' --- enabled: true --- > Local AgentMon coordination state. Gitignored; safe to delete (it is regenerated). EOF ``` Make sure `.gitignore` contains: ```gitignore .claude/*.local.* /.agentmonitors/ ``` Either way: this file is per-developer, not committed. Without it, `agentmonitors session start` quick-exits and no automated monitoring runs during a session (a one-shot `agentmonitors daemon once` still works without it — the opt-in only gates the session-lifecycle hooks). `.agentmonitors/` is a separate runtime-state directory (per-session hook state) the daemon creates the moment a session opens — it's regenerated on every run, so it's always safe to delete. Only add `.claude/monitors/*` to `.gitignore` if the user wants monitors to stay personal; otherwise commit monitor definitions so the team shares them. --- ## Phase 3 — Author a monitor from the user's intent 1. Restate the user's intent as an outcome: *what* changed, and *what should you do about it*? 2. Scaffold with `agentmonitors init` — don't hand-write `MONITOR.md` frontmatter, it's easy to get subtly wrong: ```bash agentmonitors init --type --dir .claude/monitors # Examples: agentmonitors init watch-ts --type file-fingerprint --dir .claude/monitors agentmonitors init api-health --type api-poll --dir .claude/monitors ``` (The flag is `--type`, not `--source`.) 3. Pick the smallest source that matches the intent: | Intent | `--type` | Ask for | | --- | --- | --- | | Local files changed, created, deleted | `file-fingerprint` | `globs`; optional `cwd` | | HTTP response/status changed | `api-poll` | `url`; optional `method`, `headers`, `auth`, `change-detection`, `interval` | | Output of a command/script changed (e.g. `git status`, a health-check script) | `command-poll` | `command` (argv array, not a shell string); optional `interval`, `change-detection`, `cwd`, `env`, `timeout` | | Time-based reminder or recurring check | `schedule` | `cron`; optional `timezone`, `label` | | Local git ref advances touching given paths | `incoming-changes` | `paths`; optional `cwd`, `branch`, `interval` | If none of these fit, say so — it isn't monitorable yet. Minimal `command-poll` shape: ```yaml watch: type: command-poll command: - git - status - --porcelain ``` `command` is an argv array. Default `change-detection.strategy` is `text-diff`; use `json-diff` when the command's output is JSON. 4. **Choose urgency by intent — this controls when you're notified:** | Intent | `urgency` | When delivered | | --- | --- | --- | | Interrupt mid-turn the moment it happens ("stop me if the build breaks") | `high` | At the next prompt/tool boundary, after the change has settled for ~15s | | Surface at the next natural pause; don't interrupt an in-progress turn | `normal` (default) | A brief reminder at turn boundaries; full detail at session recap | | Only worth mentioning when idle or at session start | `low` | Session recap only | **For "notify me when it changes," use `urgency: high`.** A `normal`-urgency monitor produces only a short reminder mid-turn, not the full body — the details arrive at the next `SessionStart` recap instead. If the user wants to be interrupted, `high` is correct. Detection latency is **at least 30–45s** in the default configuration — see the fast-test setup in Phase 5 for shortening this while you verify. 5. Ask only for the fields the chosen source requires; default everything else. Add `notify:` only if the user wants specific batching/throttling behavior. 6. Edit `.claude/monitors//MONITOR.md` (or a flat `.claude/monitors/.md`). The body is your handling instruction — what to do when it fires — not facts already in `watch:`. ```markdown When this fires, inspect the change and decide whether implementation or docs need follow-up. ``` --- ## Phase 4 — Validate Run this after every edit and fix everything it reports: ```bash agentmonitors validate .claude/monitors ``` --- ## Phase 5 — Verify it actually fires (mandatory) Validation proves the file parses. It does **not** prove you'll be notified. Those are different claims — `monitor explain` can show a materialized event that was never delivered to a session. **The monitor is not done until you've proven a delivered event, end to end.** ### Run `agentmonitors verify` ```bash agentmonitors verify ``` This is the whole proof in one command, and it's host-agnostic (Phase 1c hosts can use it too, minus the automatic hook wiring): it boots an isolated daemon on a throwaway socket and database, registers a throwaway session, triggers a real change, waits for the event to materialize, and claims it through the same delivery path a live hook uses — then tears everything down. Check the exit code: `0` means PASS, non-zero means FAIL with the failing stage named directly. Prefer `--format json` if you want to branch on the result programmatically instead of parsing text (spec 005 §16 documents the stable JSON shape: `ok`, `monitorId`, `stages`, `failure`, `additionalContext`, `daemonStderr`, `elapsedMs`). **Auto-trigger only covers `file-fingerprint`.** For a literal single-file glob (e.g. `docs/notes.md`), it edits the watched file itself and restores it on exit. For a pattern glob, it writes a scratch sibling that reuses the glob's static directory prefix and extension — but that placement can't fabricate a match for a glob whose filename segment is itself a wildcard (e.g. `file-?.md`) or whose only variability is a wildcard directory with a literal filename (e.g. `data-*/report.md`); those have no derivable sibling. For every other source — `api-poll`, `command-poll`, `schedule`, `incoming-changes` — and those un-fabricatable file-fingerprint globs, have `verify` run the change itself with `--trigger-cmd`: ```bash agentmonitors verify --trigger-cmd '' ``` `--trigger-cmd` is the **decoupled trigger**: after baseline, `verify` runs your shell command (from the workspace directory) to cause the watched change, then observes and delivers — one self-contained, non-interactive command. **This is the mode to use as an agent**, because `--manual` (below) blocks and does not read stdin, so a call-and-return harness (one shell command per tool call) cannot make the change while it waits. For a `command-poll` watching `git status --porcelain`, that's e.g. `--trigger-cmd 'touch new-file.txt'`; **you still have to know what change actually registers for that source** — see "Per-source trigger recipes" in the appendix (e.g. `file-fingerprint` needs a content change, not just a `touch`; `command-poll` diffs command output between ticks; `schedule` needs a cron that fires soon). The command's effects are not reverted, and a non-zero exit is a `setup` failure (fix the command, not the monitor). `--manual` is the alternative when you'd rather make the change out-of-band yourself: ```bash agentmonitors verify --manual ``` It **blocks** for the detect budget and watches for a change you make in a _separate_ step — it is _not_ an interactive stdin prompt. With a persistent shell you can background the run (`verify … --manual --timeout-ms &`), make the change, then read the result; a call-and-return harness can't, and should use `--trigger-cmd` instead. `--manual` and `--trigger-cmd` are mutually exclusive. **If the user wants a stakeholder-presentable proof**, or you want the real workspace daemon left running afterward so a follow-up `agentmonitors doctor` also goes green, add `--use-workspace-daemon`. This requires the project to already be enabled (Phase 2) — it runs `verify` against the real workspace daemon/database instead of a throwaway one and leaves it running rather than tearing it down. Because that daemon persists, `verify` cleans up after itself by retracting its scratch file's create event and leaving a short-lived **suppression** so the daemon erases the scratch file's later deletion event on its own — so the scratch change never reaches a real session and the run finishes in about the same time as a plain `verify`. An interrupted run (e.g. a command timeout) leaves no permanent stray session or event behind. Note that `verify`'s own synthetic trigger is a scratch probe: its PASS is not persisted as a durable event, so it will **not** show up in `agentmonitors events list` or `agentmonitors doctor`'s event counts. The PASS proves delivery end-to-end; if the user also wants a durable, queryable artifact to inspect after the run, have them make one real edit to a watched file and deliver it (a live session, or `agentmonitors hook deliver`), then inspect `agentmonitors events list --session `. **Success looks like** a `PASS` line, with a `deliver` stage reporting `claimed at turn-interruptible` (for `urgency: high`) or `claimed at post-compact` (`normal`/`low`), followed by the delivered `additionalContext` — that's exactly what a live hook would inject into the agent's next turn: ```json { "continue": true, "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "AgentMon: monitored changes are pending — consider handling them before continuing.\n\n### (high)\n..." } } ``` (That's the shape a live `UserPromptSubmit` hook receives; `verify`'s own PASS output prints the raw `additionalContext` text, not this wrapper.) If `verify` fails, the `FAIL` line names the stage and reason directly — don't guess from empty output the way the fully-manual recipe below forces you to: - `no-change` / `no-files-matched` means the trigger didn't do anything the source could detect (e.g. a `touch` on a file whose content didn't change) — fix the trigger, don't retry hoping it resolves itself. - `budget-exceeded` means the change was never detected within the derived wait budget — `--timeout-ms` to extend it, or run `agentmonitors monitor explain ` to see where the pipeline actually stalled. - `daemon-died` prints the daemon's own captured stderr — that's the real crash reason, not an ambiguous timeout. For debugging an individual pipeline stage by hand, or a host without `agentmonitors verify` available, see "Appendix: Advanced — manual, host-agnostic verification" at the end of this document. --- ## Phase 6 — Debug loop If `agentmonitors verify` failed, its `FAIL` line and `--format json` output already name the stage and reason — that's usually enough. Its daemon and database are temporary and deleted on exit (unless you passed `--use-workspace-daemon`, in which case they're the real workspace ones and `monitor explain`/`doctor` already see them with no extra flags), so there's no state to inspect after a plain `verify` run beyond what it already printed. If you ran the appendix's fully manual recipe instead (which pins `AGENTMONITORS_DB` by hand), see that appendix's own debug notes for reading back its persisted state. ### First: is anything still listening? `verify` proves delivery works **once**, at setup time. It does not stay true. Before digging into a specific monitor, check whether a delivery transport is still listening for this workspace at all: ```bash agentmonitors doctor ``` Read the **Delivery transports** section and its verdict line (`delivery to active sessions in this workspace → via {hook | channel | both | none}`). It names the listening method and, when delivery is currently blocked, which of these it is — each with its own fix: - **`daemon-unreachable`** — there is no daemon for this workspace (it was reaped, or never started). Nothing can deliver. Run `agentmonitors daemon run`, or open a session in this workspace. - **`workspace-mismatch`** — the transport is bound to a *different workspace* than the monitors you're waiting on. Usually means the session was launched from somewhere other than the repo. Start a session from the repo directory. - **`reminders-suppressed`** — everything is up, but reminders are **muted**: an earlier unread event is already claimed, so new ones won't surface (`coalesced-until-ack`). `doctor`'s own `remediation[]` names the exact fix — `agentmonitors events ack --session --event-ids --socket `, scoped to precisely the claimed events holding the reminder back and the daemon `doctor` diagnosed. Don't run a bare `--session ` yourself: with no `--event-ids` it acknowledges *every* unread event for that session, including work never claimed or surfaced. This one is worth knowing about, because nothing looks broken while it is happening. - **`heartbeat-stale`** — a channel server registered but stopped reporting; reconnect the MCP server or start a new session. `agentmonitors doctor --format json` exposes the same thing as `transports[]`, `deliveryWillReachThisSession`, `deliverable`, and `remediation[]`. ### Then: why didn't this monitor fire? When the user says "it didn't fire" and the transports are healthy, don't guess — run: ```bash agentmonitors monitor explain --dir .claude/monitors ``` This reads persisted runtime state (recent observations, materialized events, session state) **directly from disk — no live daemon required.** It prints a status per pipeline stage, then a **Verdict** naming where the signal stopped: - `definition` — parse/schema/source config problem; edit `MONITOR.md`, then re-run `validate`. - `scheduling` — the daemon isn't running or the monitor isn't due yet; enable the project, start a session, or check the interval/cron. - `observation` — the source ran but errored, rebaselined, or saw no change; inspect the source-specific config and state. - `notify` — a debounce/throttle hold is in effect; wait, or adjust `notify:`. - `materialization` — the source observed a change but no event was written; inspect the runtime error details in the output. - `delivery` — an event exists but no lead session is available, or it's already unread/claimed/acknowledged. If `monitor explain`'s delivery verdict disagrees with what you expect, the authoritative check is `events list` — but note that **`events list` needs a reachable daemon** (unlike `monitor explain`, it has no offline fallback and errors if none is running): ```bash agentmonitors session list # find the AgentMon session id agentmonitors events list --session --unread # requires a live daemon ``` Non-empty output confirms the event reached the session and is pending delivery — the `monitor explain` delivery verdict may simply be stale. If `events list` is also empty (once the daemon is confirmed running), the event never reached the session; work backward through the Verdict stages above. **`--unread` means unacknowledged, not "never seen."** It matches every event this session hasn't run `events ack` on yet — including one already surfaced once at a delivery lifecycle. Each row's `deliveryState` field (`unread`, `claimed`, or `acknowledged`) tells you which: `claimed` means the event already reached a hook delivery and is waiting on `events ack`, not stuck undelivered. --- ## Appendix: Advanced — manual, host-agnostic verification `agentmonitors verify` above covers the common case. This appendix drives the exact same daemon → session → event → delivery pipeline **by hand, one step at a time** — useful for debugging an individual pipeline stage, or a host without `agentmonitors verify` available. It works even outside a live Claude Code session. ### Why not just use `agentmonitors session start`? `session start` is designed for the real `SessionStart` hook: it lazy-boots a daemon with automatic idle reaping (5 minutes by default), which is fine in a live session where hooks keep the daemon alive, but can reap mid-way through a slower manual verification. Use the explicit recipe below instead, which pins everything to one daemon on one socket that never reaps. ### Speed it up for the test `agentmonitors verify` derives its own poll budget automatically — this shortening step is only useful for the manual recipe below, which needs its poll loops sized by hand. Default poll interval is 30s (`file-fingerprint`, `command-poll`) or 5min (`api-poll`). For a verification pass only, shorten it in the `MONITOR.md` frontmatter, and restore the real value afterward. `file-fingerprint` takes the same `watch.interval` knob as `command-poll` — it isn't command-poll-only: ```yaml watch: type: file-fingerprint globs: - '**/*.ts' interval: 5s # shorten for testing only notify: strategy: debounce settle-for: 5s # shorten for testing only urgency: high ``` ```yaml watch: type: command-poll command: [cat, tracked/state.txt] interval: 5s # shorten for testing only notify: strategy: debounce settle-for: 5s # shorten for testing only urgency: high ``` You can also pass `--poll-ms ` to `daemon run` (default 30000) to shorten the daemon's own tick rate — but that only controls the daemon's tick granularity, not any individual monitor's due time; `watch.interval` above (or the `api-poll`/`schedule` equivalents) is what actually governs when a specific monitor comes due. Budget step 4's poll loop below (event materialization) the same way step 5 budgets `hook deliver`: roughly `interval + settle-for`, before assuming nothing happened. ### The recipe Use an explicit socket so every step talks to the same daemon, independent of whether the project has an enabled `.claude/agentmonitors.local.md`: ```bash CWD=$(pwd) HOST_ID="verify-$(date +%s)" SOCKET="/tmp/agentmon-verify-$$.sock" # Isolate this recipe's own runtime state from any other daemon on the # machine (and from a previous run of this same recipe in the same # directory). Without this, a rerun can reuse a prior baseline and skew the # tick-count assumptions in the per-source recipes below (issue #338). export AGENTMONITORS_DB="/tmp/agentmon-verify-$$.db" # 1. Start a daemon that never idle-reaps, on an explicit socket every later # step will also target. agentmonitors daemon run .claude/monitors --socket "$SOCKET" --reap-after-ms 0 --poll-ms 5000 & DAEMON_PID=$! sleep 1 # 2. Open a lead session on the same socket, capturing the AgentMon session # id (it is NOT the same as $HOST_ID) via --format id — prints just the # bare id, no JSON parsing needed. AGENTMON_SESSION_ID=$(agentmonitors session open --socket "$SOCKET" --host-session-id "$HOST_ID" --role lead --workspace "$CWD" --format id) echo "AgentMon session: $AGENTMON_SESSION_ID" # 2b. Wait a full poll interval (matching --poll-ms above) before triggering # anything. A monitor with no prior observation is always "due," so the # daemon's first tick for it runs immediately at startup — before waiting # --poll-ms, and independent of step 2's session-open, which only # registers a delivery recipient and does not affect tick timing — and # every bundled source except `schedule` treats that first tick as a # silent baseline for *change* observations (see "Per-source trigger # recipes" below; `command-poll` is a partial exception — a first-ever # command that fails still surfaces a health observation on that tick). # This wait guarantees the baseline tick has already completed before # step 3. sleep 5 # 3. Trigger the monitored condition (per-source recipes below). # 4. Poll `events list` until the materialized event shows up. --unread always # talks to the live daemon over the socket (it errors if the daemon isn't # reachable — start it first, as above). This loop's 20 x 2s = 40s budget # assumes the shortened `interval` + `settle-for` from "Speed it up for the # test" above (5s + 5s here); at default/unshortened values (e.g. # file-fingerprint's 30s default interval with no override), widen the # retry count to cover `interval + settle-for` — the same formula step 5 # budgets for `hook deliver`, one stage later. for i in $(seq 1 20); do OUT=$(agentmonitors events list --socket "$SOCKET" --session "$AGENTMON_SESSION_ID" --unread --format json) [ "$(node -e "console.log(JSON.parse(process.argv[1]).length)" "$OUT")" -ge 1 ] && break sleep 2 done echo "$OUT" # 5. Simulate the UserPromptSubmit hook: claim any pending deliveries and # confirm the agent would actually be notified. Empty stdout usually means # nothing was claimable yet — poll the same way step 4 does. But empty # stdout is also how several misconfigurations look (workspace not # enabled, daemon unreachable, ...), so if the loop never returns content, # run `agentmonitors hook deliver --debug` (writes a step-by-step # diagnosis to stderr) to tell the two apart. for i in $(seq 1 20); do OUT5=$(echo "{\"session_id\":\"$HOST_ID\",\"cwd\":\"$CWD\",\"hook_event_name\":\"UserPromptSubmit\"}" \ | agentmonitors hook deliver --socket "$SOCKET") [ -n "$OUT5" ] && break echo "(hook deliver: nothing claimable yet, retrying...)" >&2 sleep 2 done echo "$OUT5" # 6. Clean up. kill "$DAEMON_PID" ``` **Success signal:** step 4 prints at least one event row (monitor id, urgency, title). Step 5 (`hook deliver`) returning a non-empty JSON object with a populated `hookSpecificOutput.additionalContext` confirms the delivery hook would actually notify the agent: ```json { "continue": true, "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "AgentMon: monitored changes are pending — consider handling them before continuing.\n\n### (high)\n..." } } ``` **If step 4 or step 5's loop keeps retrying, don't assume it's just a settle window — check what the daemon actually recorded first:** ```bash agentmonitors monitor history --socket "$SOCKET" ``` A row whose result column shows `no-change` means the trigger in step 3 didn't actually alter anything the source could detect (e.g. a `touch` on a file whose content didn't change under `file-fingerprint`'s content-hash comparison) — fix the trigger, don't keep waiting. A row showing `suppressed` means the opposite: the source detected a real change (the trigger worked), but a debounce/throttle hold in `notify:` is delaying it from becoming an event this tick — expected mid-settle, not a broken trigger. Wait for the next tick, or check `monitor explain`'s notify stage. Only once the result column shows `triggered` — or step 4 has already printed an event row — is a still-empty step 5 loop for a `high`-urgency monitor expected, not a bug. `events list` (step 4) surfaces an event as soon as it materializes. `hook deliver` at the `turn-interruptible` lifecycle applies a *separate*, fixed ~15s "claim settle" window measured from the event's own creation time before it will surface the event's body — independent of your monitor's `notify.settle-for`. So for `high` urgency, budget roughly `interval + settle-for + 15s` before step 5's loop returns content — the 20 × 2s retry window above comfortably covers that. **Do not** change any files or re-open the session while you wait for step 5 once the event already exists — that resets the condition you're trying to observe. A `normal`-urgency monitor doesn't have this extra wait: `hook deliver` surfaces a reminder (not the full body) as soon as the event is unread (002 §9.2). `low` urgency is delivered only at the `turn-idle` lifecycle (002 §9.3, §13.2) — this recipe's step 5 sends `UserPromptSubmit`, which maps to `turn-interruptible` only, so it never exercises low-urgency delivery; expect step 5 to keep returning empty for a `low`-urgency monitor regardless of how long you wait. **This recipe's daemon is invisible to `doctor`.** Everything above runs against the explicit `$SOCKET` / `$AGENTMONITORS_DB`. `agentmonitors doctor` and `monitor explain` auto-discover the *workspace's own* socket — falling back to the shared global default only when the workspace isn't enabled — so neither ever resolves this recipe's throwaway `$SOCKET` (both still honor `AGENTMONITORS_DB` if it's set in their environment). Running plain `agentmonitors doctor` right after a successful run of this recipe is expected to still report the monitor "never observed" or the daemon unreachable — that's a different daemon than the one `doctor` resolved, not a regression. To check the setup a real agent session would actually use, start a daemon on the workspace's own socket (`agentmonitors daemon run` — no `--socket`) or open a live session, then re-run `doctor`. **For a stakeholder-presentable proof** (e.g. showing a security reviewer that monitoring is actually wired up), don't screenshot the isolated-socket recipe's output — it's throwaway and proves the mechanism, not the live setup. Instead, start the workspace's own daemon (`agentmonitors daemon run`, no `--socket`) and screenshot `doctor`'s all-green summary alongside the `hook deliver` JSON from step 5 above. ### Per-source trigger recipes (step 3) A monitor with no prior observation is always "due," so the daemon's very first tick for it runs immediately at startup — before waiting `--poll-ms` at all. `file-fingerprint`, `api-poll`, `command-poll`, and `incoming-changes` all treat that first tick as a **silent baseline**: whatever state exists at that moment becomes the reference point, and no *change* observation is ever emitted for it. A change that lands *before* this first tick finishes is folded straight into the baseline and is never detected — not on that tick, not on any later one, because later ticks diff against the state the *previous* tick captured, not against "what changed since the daemon started." The one exception is `command-poll`'s health tracking: if the command's first-ever execution *fails*, that failure isn't folded into a silent baseline — it still surfaces a `Command failing: …` health observation on tick 1, because there is no prior "ok" state for the failure to be silently reconciled against. `schedule` has no baseline: it emits an observation on any tick where its cron matches, from the first eligible tick onward. Step 2b's wait exists precisely to dodge this race — by the time you reach step 3, the baselining first tick has already completed, so whatever you trigger next is guaranteed to be detected on a subsequent tick. **`file-fingerprint`** — change the *content* of a file matched by `watch.globs`. This source detects changes by content hash, not mtime or existence, so a bare `touch` on an existing file leaves the hash unchanged and is silently ignored — append real content instead: ```bash echo "// verify $(date)" >> path/to/monitored/file.txt ``` **`command-poll`** — change the command's output between two ticks. Example, watching `cat tracked/state.txt`: ```bash echo "changed" >> tracked/state.txt ``` Each tick after the baseline diffs against the *previous* tick's captured output (a rolling comparison), so once the baseline tick has run, whichever tick executes after you make the change will detect it. This assumes a fresh baseline, which is why the recipe isolates `$AGENTMONITORS_DB` above — reusing a database from a prior run of this same recipe means the daemon's first tick already has a baseline from that earlier run. **Gotcha, `git status --porcelain` monitors specifically:** this is `command-poll`'s analog of the `file-fingerprint` `touch` no-op above. `git status --porcelain` reports an already-untracked file as `?? path` regardless of its content — appending to it again doesn't change that line, so re-touching an existing untracked file is a silent no-op trigger here too. The trigger must add, remove, or modify a *tracked* file, or introduce a genuinely *new* untracked path — not write again to a file that's already untracked. **`api-poll`** — the response from `watch.url` must change between two ticks. Point it at a controllable local server, or a source that changes every poll. Without a controllable endpoint, `agentmonitors monitor test .claude/monitors//MONITOR.md` confirms the source is configured and reachable, but an actual fire needs the remote resource to change on its own. **`schedule`** — set a cron that fires within the next minute while testing (e.g. `'* * * * *'`), then restore the real cron afterward. `agentmonitors monitor test ` confirms the cron parses. No baseline race here — just make sure the cron is set *before* starting the daemon, so its first eligible tick can catch the matching minute. **`incoming-changes`** — advance the tracked ref by committing to a watched path, then trigger a fetch/merge that advances it (or simulate with `git pull`): ```bash touch docs/scratch-verify.txt git add docs/scratch-verify.txt git commit -m "verify incoming-changes monitor" --no-gpg-sign ``` --- ### Reading back the manual recipe's state This recipe's daemon is dead once its step 6 (`kill "$DAEMON_PID"`) runs, and its socket is invisible to `doctor`/`monitor explain` even while it's alive — those auto-discover the *workspace's own* socket (falling back to the shared global default only when the workspace isn't enabled), never this recipe's throwaway `$SOCKET`. What does survive is the SQLite file `AGENTMONITORS_DB` pointed at (`/tmp/agentmon-verify-.db`): `monitor explain` and `monitor history` both resolve their database via the `AGENTMONITORS_DB` environment variable, so pointing it at that same file — e.g. `AGENTMONITORS_DB=/tmp/agentmon-verify-.db agentmonitors monitor explain --dir .claude/monitors` — reads the persisted state from that run **in-process, no live daemon required.** (`agentmonitors verify`'s own isolated daemon, by contrast, deletes its temp database on exit — there's nothing to read back after a plain `verify` run; its own PASS/FAIL output is the full record. See Phase 6 above for the general debug loop.)