Skip to main content
Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see Install and update.
Poll RSS, JSON APIs, and GitHub with watermark dedup.

​
Skill metadata

​
Reference: full SKILL.md

The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

​
Watchers

Poll 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).

​
When to Use

  • User wants to watch an RSS/Atom feed and be notified of new entries
  • User wants to watch a GitHub repo’s issues / pulls / releases / commits
  • User wants to poll an arbitrary JSON endpoint and get notified on new items
  • User asks for “a watcher for X” or “notify me when X changes”

​
Mental model

A watcher is just a script that:
  1. Fetches data from the external source
  2. Compares against a watermark file of previously-seen IDs
  3. Writes the new watermark back
  4. Prints new items to stdout (or nothing on no-change)
The 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.

​
Ready-made scripts

All three live in $mibyan_HOME/skills/devops/watchers/scripts/ once the skill is installed. Each reads WATCHER_STATE_DIR (defaults to $mibyan_HOME/watcher-state/) for its state file, keyed by the --name argument. All three:
  • First run records a baseline — never replays existing feed
  • Watermark is a bounded ID set (max 500) to cap memory
  • Output format: ## <title>\n<url>\n\n<optional body> per item
  • Empty stdout on no-new — the caller treats that as silent
  • Non-zero exit on fetch errors

​
Usage

Run a watcher directly from the terminal tool:
Watch a GitHub repo (set GITHUB_TOKEN in ${mibyan_HOME:-~/.mibyan}/.env to avoid the 60 req/hr anonymous rate limit):
Poll an arbitrary JSON API:

​
Wiring into cron

Ask the agent to schedule a cron job with a prompt like:
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.
The 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.

​
State files

Every watcher writes $mibyan_HOME/watcher-state/<name>.json. Inspect:
Force a replay (next run treated as first poll):

​
Writing your own

All 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.

​
Common Pitfalls

  1. 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.
  2. 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.
  3. Unbounded watermark growth. The shared helper caps at 500 IDs. Raise it for high-churn feeds; lower it on constrained filesystems.
  4. Putting the state dir where the agent’s sandbox can’t write. $mibyan_HOME/watcher-state/ is always writable. Docker/Modal backends may not see arbitrary host paths.