| name | monitor-inbox |
| description | Monitor INCOMING Pushover notifications (the messages that ARRIVE on the account — e.g. noip-ddns self-healer alerts) from a Claude Code session, via the Pushover Open Client API. On-demand pull, not a background daemon. Register a dedicated receive-device once (masked account-password prompt, password never stored), then pull new messages headlessly into a local JSONL inbox. Use when the user asks to read, check, watch, or monitor received/incoming Pushover messages, or what alerts landed. TRIGGERS - monitor pushover, incoming pushover, received notifications, check pushover inbox, what alerts arrived, pull pushover messages, read incoming alerts. |
monitor-inbox
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
The rest of pushover-commander only sends; its audit log (po-audit.jsonl)
can never show what arrived. This skill wraps the Pushover Open Client API
(the REST surface the desktop/mobile apps use to receive) so a session can read
incoming notifications. Core: _lib/pushover_inbox.ts.
Model = on-demand pull (run pull when asked; no background daemon).
Commands
CORE="$(cc-plugin-root pushover-commander)/skills/_lib/pushover_inbox.ts"
env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" register [--name claude-mac] [--force]
env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" pull [--json] [--limit N]
bun "$CORE" list [--limit N] [--json]
env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" doctor
One-time setup (operator must run register)
Only the operator can type the account password, so guide them to run register
themselves (or run it and let them type into the masked prompt). After that,
pull/list/doctor all work headlessly — no password, no Touch ID — because the
client secret + device_id live in the vault automation tier (agent-readable).
Secret handling (SCS doctrine — cc-skills/docs/self-custody-secrets.md)
| Secret | Class | Where it lives |
|---|
| Account email + password | crown jewel | masked prompt, in-memory only — never stored / never sent / never in argv or transcript |
client secret + device_id | automation token | SCS vault scope pushover (agent-readable, so headless pull needs no prompt) |
Never Pushover, email, commit, or otherwise transmit any of these off-machine.
Caveats (verified 2026-07-05)
- No history back-fill. A freshly-registered Open-Client device only receives
messages sent after registration. It will NOT pull the alerts already sitting
in the native Pushover.app. Register first, then future alerts arrive.
- IMAP-style queue.
messages.json returns the pending queue; pull calls
update_highest to ack, else the same messages re-download every time.
- Desktop/Open-Client license. Registering a receive-device may require a
Pushover Desktop license on the account. If so,
/1/devices.json errors — the
message is surfaced verbatim by register.
- 2FA. If the account has two-factor enabled,
register re-prompts for the code
and retries login.
- Proxies. Always
env -u HTTPS_PROXY -u HTTP_PROXY for the network commands, so
Pushover HTTPS bypasses the sandbox MITM proxy (otherwise 502).
Files
- Core:
_lib/pushover_inbox.ts
- Inbox log:
~/.local/state/pushover/po-inbox.jsonl (UUID-keyed, sits beside the
send-side po-audit.jsonl); override with PUSHOVER_INBOX_PATH.
- Creds: SCS vault scope
pushover → client.secret, client.device_id,
client.device_name.
Post-Execution Reflection
After this skill completes, check before closing:
- Did
pull actually ack? If the same messages reappear on the next pull,
update_highest isn't landing — fix the ack path, not the reader.
- Did the operator expect an alert that didn't arrive? Confirm it was sent
after
register (no back-fill) before assuming a bug.
- Any credential leak surface? The account password must never appear in a log,
argv, the inbox JSONL, or a transcript. If it did, that's a real defect — fix now.
Only update if the issue is real and reproducible — not speculative.
