watch

name

watch

description

Start (or stop) the nyann CI sentinel for the current repo, OR manage a multi-repo watch-list and poll all watched repos at once. The sentinel polls open PRs for state transitions (CI failure, approval, merge, branch staleness) and emits notifications the session-start hook surfaces on your next prompt. TRIGGER when the user says "watch this PR", "watch my PRs", "ping me when CI passes", "tell me when CI fails", "background watch", "keep watching after I close this", "run the sentinel in the background", "daemonize the watcher", "watch in the background", "/nyann:watch", "/nyann:watch --pr <N>", "/nyann:watch --daemon", "stop watching", "/nyann:watch --stop". ALSO TRIGGER for multi-repo aggregation: "watch all my repos", "watch across repos", "add a repo to my watch list", "add <owner/repo> to watch", "remove <owner/repo> from watch", "list watched repos", "what's new across all my repos", "poll every repo I'm watching", "/nyann:watch --add", "/nyann:watch --remove", "/nyann:watch --list". Do NOT trigger on "wait for checks" — that is `/nyann:wait-for-pr-checks` (blocking poll). watch is fire-and-forget; wait-for-pr-checks blocks.

watch

Plugin root: <plugin_root>/skills/watch/SKILL.md — scripts live at <plugin_root>/bin/ci-sentinel.sh, bin/sentinel-daemon.sh, bin/sentinel-aggregate.sh, and bin/read-notifications.sh.

Two modes:

• Single repo (Steps 1–3): poll the current repo's PRs directly — one-shot, or as a supervised background daemon (--daemon).
• Multi-repo (Step 4): keep a watch-list of repos and poll them all under one rate-limit-aware scheduler. Use this when the user watches PRs across several repos and wants one merged view.

Step 1: Resolve repo

Use gh repo view --json nameWithOwner --jq .nameWithOwner to get the <owner>/<repo> slug for the current directory. If gh is missing or the repo has no GitHub remote, tell the user to set one up and stop.

Step 2: Start, stop, or list

If the user said "stop" / --stop, stop BOTH a one-shot poll and any backgrounded daemon (the daemon stop tears down the supervisor unit too):

bash <plugin_root>/bin/sentinel-daemon.sh stop --repo <owner/repo>

For a single foreground poll cycle (default — fire-and-forget):

bash <plugin_root>/bin/ci-sentinel.sh --repo <owner/repo> [--pr <N>]

The sentinel is one-shot per invocation — each run polls the named PR(s) once and writes notification entries to ~/.claude/nyann/notifications/<repo-hash>.jsonl.

Backgrounded daemon (--daemon) — opt-in

Only when the user explicitly asks to keep watching after the session ends (--daemon, "background watch", "keep watching after I close this"), offer the supervised daemon. Do not start it implicitly — a long-running background process is opt-in, mirroring the session-triage hook-install precedent. Confirm first, then:

bash <plugin_root>/bin/sentinel-daemon.sh start --repo <owner/repo> [--pr <N>]

This launches ci-sentinel.sh --daemon-loop under a platform supervisor (launchd on macOS, a systemd user unit on Linux, nohup fallback otherwise) so it survives the terminal closing. It polls every interval, backs off on gh failures, and self-terminates at --max-runtime (default 8h) as an orphan backstop. Starting is idempotent — a daemon already running for the repo is left alone.

Delivery secrets under a supervisor: if a notification delivery channel is configured, start hands its secret to the launchd/systemd session so the supervised daemon can reach it. While the daemon runs the secret is visible to your other same-user processes in that session; it is cleared on stop. (The nohup fallback inherits your shell env directly and exposes nothing extra.)

Report status (pid + supervisor + watched PRs; flags a stale daemon) with:

bash <plugin_root>/bin/sentinel-daemon.sh status --repo <owner/repo>

doctor also surfaces any running/stale sentinel so it's never invisible.

Step 3: Show outstanding notifications

After polling (or whenever the user asks "what's new on my PRs?"):

bash <plugin_root>/bin/read-notifications.sh --repo <owner/repo>

This reads all queued notifications and truncates the file. Use --peek if you want to leave the queue intact.

Render the result as a short list:

[nyann] 2 notifications since last check:
  - PR #42: CI failed (2h ago)
  - PR #43: approved (15m ago)

Step 4: Multi-repo watch-list (aggregation)

When the user watches PRs across several repos, manage a watch-list and poll them all at once instead of running the single-repo flow per repo. The watch-list lives at ~/.claude/nyann/watch-list.json (an array of {repo, prs?}); manage it via bin/sentinel-aggregate.sh, because one scheduler must own the GitHub rate budget for all repos.

Add / remove / list watched repos:

bash <plugin_root>/bin/sentinel-aggregate.sh --add <owner/repo> [--pr <N>]
bash <plugin_root>/bin/sentinel-aggregate.sh --remove <owner/repo>
bash <plugin_root>/bin/sentinel-aggregate.sh --list

--add is idempotent (re-adding never duplicates; --pr merges into the repo's PR set), so you can run it freely. Malformed slugs are rejected.

Poll every watched repo in one cycle:

bash <plugin_root>/bin/sentinel-aggregate.sh --poll

This runs ci-sentinel.sh once per repo, but a single scheduler tracks the GitHub core rate budget and backs off globally (adaptive interval, all repos) when the budget runs low — because N repos × M PRs would otherwise blow the 5000/hr ceiling. It prints a scheduler-summary JSON (current_interval tells a supervising daemon how long to sleep next).

To keep the whole watch-list polling in the background after the session ends (same opt-in confirm as the single-repo daemon — a long-running process is never started implicitly), supervise the aggregate loop via the daemon manager:

bash <plugin_root>/bin/sentinel-daemon.sh start  --aggregate
bash <plugin_root>/bin/sentinel-daemon.sh status --aggregate
bash <plugin_root>/bin/sentinel-daemon.sh stop   --aggregate

This launches sentinel-aggregate.sh --daemon-loop under launchd / systemd / nohup, sleeping each cycle's current_interval and self-capping at --max-runtime (8h). One aggregate daemon runs per user; doctor surfaces it alongside any per-repo daemons.

Read the unified, repo-tagged view across every watched repo:

bash <plugin_root>/bin/read-notifications.sh --all

Each entry is tagged with context.repo so you can say which repo it came from. --all drains every watched queue (use --peek to leave them intact). Render grouped by repo:

[nyann] 3 notifications across 2 repos:
  acme/api:
    - PR #42: CI failed (2h ago)
  acme/web:
    - PR #7: approved (15m ago)
    - PR #9: merged into main (1h ago)

When to hand off

• "Wait until CI passes" → wait-for-pr-checks (blocking).
• "Merge the PR when CI passes" → ship (PR + merge in one step).