watchers

1---2name: watchers3description: Poll RSS, JSON APIs, and GitHub with watermark dedup.4version: 1.0.05author: Hermes Agent6license: MIT7platforms: [linux, macos]8metadata:9  hermes:10    tags: [cron, polling, rss, github, http, automation, monitoring]11    category: devops12    requires_toolsets: [terminal]13    related_skills: []14---15 16# Watchers17 18Poll external sources on an interval and react only to new items. Three ready-made scripts plus a shared watermark helper; wire them into a cron job (or run them ad-hoc from the terminal).19 20## When to Use21 22- User wants to watch an RSS/Atom feed and be notified of new entries23- User wants to watch a GitHub repo's issues / pulls / releases / commits24- User wants to poll an arbitrary JSON endpoint and get notified on new items25- User asks for "a watcher for X" or "notify me when X changes"26 27## Mental model28 29A watcher is just a script that:30 311. Fetches data from the external source322. Compares against a watermark file of previously-seen IDs333. Writes the new watermark back344. Prints new items to stdout (or nothing on no-change)35 36The scripts below handle all three. The agent runs them via the terminal tool — from a cron job, a webhook, or an interactive chat — and reports what's new.37 38## Ready-made scripts39 40All three live in `$HERMES_HOME/skills/devops/watchers/scripts/` once the skill is installed. Each reads `WATCHER_STATE_DIR` (defaults to `$HERMES_HOME/watcher-state/`) for its state file, keyed by the `--name` argument.41 42| Script | What it watches | Dedup key |43|---|---|---|44| `watch_rss.py` | RSS 2.0 or Atom feed URL | `<guid>` / `<id>` |45| `watch_http_json.py` | Any JSON endpoint returning a list of objects | Configurable id field |46| `watch_github.py` | GitHub issues / pulls / releases / commits for a repo | `id` / `sha` |47 48All three:49 50- First run records a baseline — never replays existing feed51- Watermark is a bounded ID set (max 500) to cap memory52- Output format: `## <title>\n<url>\n\n<optional body>` per item53- Empty stdout on no-new — the caller treats that as silent54- Non-zero exit on fetch errors55 56## Usage57 58Run a watcher directly from the terminal tool:59 60```bash61python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \62  --name hn --url https://news.ycombinator.com/rss --max 563```64 65Watch a GitHub repo (set `GITHUB_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` to avoid the 60 req/hr anonymous rate limit):66 67```bash68python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \69  --name hermes-issues --repo NousResearch/hermes-agent --scope issues70```71 72Poll an arbitrary JSON API:73 74```bash75python $HERMES_HOME/skills/devops/watchers/scripts/watch_http_json.py \76  --name api --url https://api.example.com/events \77  --id-field event_id --items-path data.events78```79 80## Wiring into cron81 82Ask the agent to schedule a cron job with a prompt like:83 84> Every 15 minutes, run `watch_rss.py --name hn --url https://news.ycombinator.com/rss`. If it prints anything, summarize the headlines and deliver them. If it prints nothing, stay silent.85 86The agent invokes the script via the terminal tool inside the cron job's agent loop; no changes to cron's built-in `--script` flag are needed.87 88## State files89 90Every watcher writes `$HERMES_HOME/watcher-state/<name>.json`. Inspect:91 92```bash93cat $HERMES_HOME/watcher-state/hn.json94```95 96Force a replay (next run treated as first poll):97 98```bash99rm $HERMES_HOME/watcher-state/hn.json100```101 102## Writing your own103 104All three scripts use the same template: load watermark, fetch, diff, save, emit. `scripts/_watermark.py` is the shared helper; import it to get atomic writes + bounded ID set + first-run baseline for free. See any of the three reference scripts for how little boilerplate it takes.105 106## Common Pitfalls107 1081. **Printing a "no new items" header every tick.** Callers rely on empty stdout = silent. If you print anything on an empty delta, you spam the channel. The shipped scripts handle this; custom scripts must too.1092. **Expecting the first run to emit items.** It won't — first run records a baseline. If you need an initial digest, delete the state file after the first run or add a `--prime-with-latest N` flag in your own script.1103. **Unbounded watermark growth.** The shared helper caps at 500 IDs. Raise it for high-churn feeds; lower it on constrained filesystems.1114. **Putting the state dir where the agent's sandbox can't write.** `$HERMES_HOME/watcher-state/` is always writable. Docker/Modal backends may not see arbitrary host paths.112 113