watch

Watch

Run background event watchers using the CC Monitor tool. Each stdout line from the subprocess becomes a conversation notification. Silence costs zero tokens.

Two classes:

• Stream: Source pushes events (tail -f, WebSocket, fswatch). Truly event-driven.
• Poll: Script checks on interval, emits only on change. Same polling model, less noise.

Usage

/claude-code-hermit:watch <instruction>            — start ad-hoc (poll, default 5m interval)
/claude-code-hermit:watch <stream-command>         — start ad-hoc stream
/claude-code-hermit:watch start                    — register all enabled config watches
/claude-code-hermit:watch stop [id]                — stop by id (or auto if 1 active)
/claude-code-hermit:watch stop --all               — stop all watches
/claude-code-hermit:watch status                   — list active watches from registry

Runtime Registry

All active watches are tracked in .claude-code-hermit/state/monitors.runtime.json. This is the sole source of truth — not SHELL.md.

{
  "monitors": [
    {
      "id": "deploy-errors",
      "task_id": "bmg9y1le3",
      "description": "errors in deploy.log",
      "started_at": "2026-04-12T15:00:00Z",
      "source": "config",
      "class": "stream"
    }
  ],
  "last_cleared": "2026-04-12T15:00:00Z"
}

SHELL.md ## Monitoring entries are a journal only — no code path reads them for decisions. Start/stop decisions read from the runtime registry.

Plan

Starting an ad-hoc watch

1. Parse instruction + optional interval from operator message. Default interval: 5m.
2. Verify active session exists (.claude-code-hermit/sessions/SHELL.md must exist). If none: "No active session. Run /claude-code-hermit:session first."
3. Generate id: adhoc-<epoch>-<4char-random> (e.g., adhoc-1744460400-a3f2). Timestamp + random suffix avoids collisions across sessions.
4. Determine command shape:
   • If instruction is a shell command (contains pipes, flags, or path): use as-is
   • If instruction is a natural language description: wrap in a poll loop:

     while true; do <check-command> && echo "<brief-event-description>"; sleep <interval_secs>; done
     

5. Invoke Monitor tool with all 4 required params:
   • description: the operator's instruction text (shown in every notification)
   • command: the constructed command
   • timeout_ms: 300000 (ignored when persistent, but always required)
   • persistent: true (runs until stopped or session ends)
6. Read state/monitors.runtime.json (create if missing: {"monitors": [], "last_cleared": null})
7. Append entry to monitors[] with source: "adhoc"
8. Write registry back
9. Log to SHELL.md ## Monitoring: - [ACTIVE] <instruction> (started HH:MM)

Starting config watches (/watch start)

Called automatically by session-start (step 11b). Can also be called manually.

1. Read config.json → monitors[], filter enabled: true
2. Read state/monitors.runtime.json
3. For each enabled config watch whose id is NOT already in the registry: a. Resolve command: Replace the literal string ${CLAUDE_PLUGIN_ROOT} with the actual env var value (available at skill execution time inside CC context; NOT available in Monitor subprocess). If the var is unset, log a warning and skip that watch. b. Invoke Monitor tool:
   • description: from config entry
   • command: the resolved command string
   • timeout_ms: config.timeout_ms ?? 300000
   • persistent: config.persistent ?? true c. Append to registry with source: "config" and the returned task_id
4. Write registry back
5. If any watches were registered: log to SHELL.md ## Monitoring: [HH:MM] Watches registered: <id1>, <id2> (<N> total)
6. If all config watches were already in the registry (idempotent): no log, no output

Stopping a watch

1. Parse id from operator message (or --all flag)
2. stop <id>: Look up task_id in registry → TaskStop → remove entry from registry → update SHELL.md [ACTIVE] to [STOPPED]
3. stop (no id):
   • Count ad-hoc watches in registry (source: "adhoc")
   • 0 active: "No active watches to stop."
   • 1 active: stop it without asking
   • 2+ active: list them, ask which one (or use --all)
4. stop --all: For each entry in registry, call TaskStop with its task_id. Clear all entries from registry. Log to SHELL.md.
5. After any stop: write registry back

Note: If TaskStop returns an error for a given task_id (the watch already died), remove the entry from the registry anyway. A dead watch's entry is stale.

Status

1. Read state/monitors.runtime.json
2. If no watches: "No active watches."
3. Display a table:

Active watches:
  ID             SOURCE   CLASS   STARTED    DESCRIPTION
  deploy-errors  config   stream  15:00      errors in deploy.log
  adhoc-...      adhoc    poll    16:30      check error rate in app metrics

Handling self-exit notifications

When a Monitor subprocess exits on its own (timeout, script crash, or clean exit), CC sends a completion notification into the conversation. On seeing this:

1. Match the task_id from the notification against the runtime registry
2. If found: remove the entry and write registry back
3. Log to SHELL.md: [HH:MM] Watch <id> exited

If the notification is missed (compaction, context pressure), the stale entry is harmless. The next session start clears the registry unconditionally.

Notes

• All 4 Monitor tool params are required. Always pass timeout_ms even when persistent: true (the tool schema requires it; the value is ignored).
• $CLAUDE_PLUGIN_ROOT is NOT available in Monitor subprocess. Resolve it at registration time. $PWD is the project root in the subprocess.
• grep --line-buffered is required in pipes. Without it, pipe buffering can delay events by minutes.
• Add || true after API calls in poll loops. One failed request shouldn't kill the watch.
• Be selective with stdout. Noisy watches are auto-stopped by CC — emit only on genuine change/event.
• Filesystem events in Docker: Use inotifywait (from inotify-tools, included in the hermit base image) instead of fswatch (macOS-only). Example stream command: inotifywait -m -r --format '%w%f %e' -e modify,create,delete src/.
• Config hot-reload: Config watches do NOT hot-reload during a session. Changes to config.json monitors only apply at the next session start or after a manual /watch stop <id> + /watch start.
• On /session-close: session-close stops all watches before archiving. The registry is cleared.
• On session start: the registry is cleared unconditionally before registering config watches. Monitors are session-scoped.