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"
# One-time, INTERACTIVE — mints a receive-device. Prompts for the Pushover ACCOUNT
# email + password (password is MASKED, used once in-memory, NEVER stored). Only the
# derived client secret + device_id are persisted, to the SCS vault scope `pushover`.
env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" register [--name claude-mac] [--force]
# On demand — fetch new messages → append to po-inbox.jsonl → ack (update_highest).
env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" pull [--json] [--limit N]
# Read back the local inbox (NO network).
bun "$CORE" list [--limit N] [--json]
# Health: creds present? device registered? API reachable / how many waiting?
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.
1---2name: monitor-inbox3description: 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.4---5
6# monitor-inbox
7
8> **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.
9
10The rest of pushover-commander only **sends**; its audit log (`po-audit.jsonl`)
11can never show what **arrived**. This skill wraps the Pushover **Open Client API**
12(the REST surface the desktop/mobile apps use to _receive_) so a session can read
13incoming notifications. Core: `_lib/pushover_inbox.ts`.
14
15Model = **on-demand pull** (run `pull` when asked; no background daemon).
16
17## Commands
18
19```bash
20CORE="$(cc-plugin-root pushover-commander)/skills/_lib/pushover_inbox.ts"
21
22# One-time, INTERACTIVE — mints a receive-device. Prompts for the Pushover ACCOUNT
23# email + password (password is MASKED, used once in-memory, NEVER stored). Only the
24# derived client secret + device_id are persisted, to the SCS vault scope `pushover`.
25env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" register [--name claude-mac] [--force]
26
27# On demand — fetch new messages → append to po-inbox.jsonl → ack (update_highest).
28env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" pull [--json] [--limit N]
29
30# Read back the local inbox (NO network).
31bun "$CORE" list [--limit N] [--json]
32
33# Health: creds present? device registered? API reachable / how many waiting?
34env -u HTTPS_PROXY -u HTTP_PROXY bun "$CORE" doctor
35```
36
37## One-time setup (operator must run `register`)
38
39Only the operator can type the account password, so **guide them to run `register`
40themselves** (or run it and let them type into the masked prompt). After that,
41`pull`/`list`/`doctor` all work headlessly — no password, no Touch ID — because the
42client secret + device_id live in the vault **automation tier** (agent-readable).
43
44## Secret handling (SCS doctrine — `cc-skills/docs/self-custody-secrets.md`)
45
46| Secret | Class | Where it lives |
47| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
48| Account email + password | **crown jewel** | masked prompt, in-memory only — **never stored / never sent / never in argv or transcript** |
49| client `secret` + `device_id` | automation token | SCS `vault` scope `pushover` (agent-readable, so headless `pull` needs no prompt) |
50
51Never Pushover, email, commit, or otherwise transmit any of these off-machine.
52
53## Caveats (verified 2026-07-05)
54
55- **No history back-fill.** A freshly-registered Open-Client device only receives
56 messages sent **after** registration. It will NOT pull the alerts already sitting
57 in the native Pushover.app. Register first, then future alerts arrive.
58- **IMAP-style queue.** `messages.json` returns the pending queue; `pull` calls
59 `update_highest` to ack, else the same messages re-download every time.
60- **Desktop/Open-Client license.** Registering a receive-device may require a
61 Pushover Desktop license on the account. If so, `/1/devices.json` errors — the
62 message is surfaced verbatim by `register`.
63- **2FA.** If the account has two-factor enabled, `register` re-prompts for the code
64 and retries login.
65- **Proxies.** Always `env -u HTTPS_PROXY -u HTTP_PROXY` for the network commands, so
66 Pushover HTTPS bypasses the sandbox MITM proxy (otherwise 502).
67
68## Files
69
70- Core: `_lib/pushover_inbox.ts`
71- Inbox log: `~/.local/state/pushover/po-inbox.jsonl` (UUID-keyed, sits beside the
72 send-side `po-audit.jsonl`); override with `PUSHOVER_INBOX_PATH`.
73- Creds: SCS vault scope `pushover` → `client.secret`, `client.device_id`,
74 `client.device_name`.
75
76## Post-Execution Reflection
77
78After this skill completes, check before closing:
79
801. **Did `pull` actually ack?** If the same messages reappear on the next `pull`,
81 `update_highest` isn't landing — fix the ack path, not the reader.
822. **Did the operator expect an alert that didn't arrive?** Confirm it was sent
83 _after_ `register` (no back-fill) before assuming a bug.
843. **Any credential leak surface?** The account password must never appear in a log,
85 argv, the inbox JSONL, or a transcript. If it did, that's a real defect — fix now.
86
87Only update if the issue is real and reproducible — not speculative.
terrylica