Notify

Notify

An autonomous loop that stalls while its operator is away stays stalled until someone happens to look. This skill is the outbound half of that gap: one script that sends a short message on a configured channel and tells the truth about whether it worked.

Reach for this when

• A caller has already decided a human needs to know something now — typically because it owns a health/escalation state machine (a supervisor's escalate state, a CI failure gate) — and needs to actually deliver that decision outside the terminal.

Do not reach for this when

• You are deciding whether something is worth interrupting a human for. That judgement belongs to the caller, not this skill. A notify that also decided when to fire would make its caller's escalation logic impossible to reason about separately.
• The task just "feels important." This is a deliberate, user-invoked tool, not a discipline the agent reaches for on its own.

What this owns, and what it does not

Owns: sending a short message on whichever channel is configured, dry-run by default, real send behind an explicit flag, dedup/rate-limit so a loop messaging on every tick doesn't become worse than silence, and a failure path that is loud rather than swallowed.

Does not own: deciding when to notify, what the message should say beyond "short and state-bearing," or wiring this into any particular watchdog or loop. That integration is the caller's job.

Channel priority

Per jonhill90/skills#146, Jon later re-ordered this (2026-08-11) once Telegram proved to be the only channel that actually reached his phone: Telegram works from any machine and does not depend on macOS automation permissions, so it goes first and iMessage becomes the fallback rather than the primary.

1. Telegram — built, tried first. Bot API over HTTPS; works from any machine, not just a Mac.
2. iMessage — built, Mac-only fallback. No credential on a Mac; Messages.app is already signed in. Tried only if Telegram isn't configured or its send fails.
3. Discord, 4. Teams — designed, not built. See references/channels.md for the shape each would take if a future change needs one. Build only if both Telegram and iMessage are genuinely blocked for a given setup — one working channel closes the operational gap; five is not the goal.
4. Slack — deferred indefinitely, unused since 2019. Do not build it.

Configuration

Everything channel- and credential-related comes from the environment. Nothing is hardcoded and nothing is committed.

Credentials must come from the environment — an untracked, 0600 env file loaded by the caller is the pattern this skill assumes, the same one agent-supervisor/scripts/supervisor/notify.sh uses. Never put a token inline in a command, a script, or anything committed to this repository. There is no config file in this repository to edit; set the environment where the caller runs.

Usage

# Dry run (default) — prints exactly what would be sent, sends nothing, exits 0.
python3 scripts/notify.py --message "watchdog: escalate — 3 restarts/hr, stopped."

# Real send, auto channel selection (Telegram, then iMessage fallback).
AGENT_NOTIFY_TELEGRAM_TOKEN="..." AGENT_NOTIFY_TELEGRAM_CHAT_ID="..." \
AGENT_NOTIFY_IMESSAGE_TO="you@example.com" \
  python3 scripts/notify.py --message "watchdog: escalate — check tmux." --send

# Force a single channel — no fallback to the other if it fails.
AGENT_NOTIFY_IMESSAGE_TO="you@example.com" \
  python3 scripts/notify.py --message "..." --channel imessage --send

• --message (required) — kept under 200 characters by the script; a message that doesn't fit on a lock screen defeats the point. State what stopped, what it needs, and where to look — not a transcript dump.
• --send — actually deliver. Every other invocation, including every test, omits this and gets a dry run instead.
• --force — bypass dedup/rate-limit suppression for one send. Use sparingly; the suppression exists because a loop that messages on every tick is worse than silence.
• --channel — override $NOTIFY_CHANNEL. auto (default) tries telegram then imessage with no further fallback once one is named explicitly. discord, teams, and slack exit 2 with a message pointing at references/channels.md, rather than silently doing nothing.

Exit codes

An unreachable channel must never look like "nothing to report" — that is the fail-open shape this comes from (jonhill90/skills#146). Exit 1 plus a local log line is the contract a caller can check.

Testing this skill

Sending a message is an outward-facing action — treat it like any other send to a live system.

• Always dry-run while iterating. Every invocation above without --send prints what would happen and touches no state, no network, no Messages.app.

• --self-test exercises the dedup, rate-limit, config-validation, and logging logic against a scratch state directory with no real send involved:

  python3 scripts/notify.py --self-test
  

• At most one live send, ever, per change. If you need to confirm the real path works, send exactly one message to yourself, clearly marked as a test, and record its exact content in whatever report you're producing. Do not loop, retry, or fan this out to confirm it "really" worked — one send is the check.

• If a self-send doesn't produce a notification, report that. Do not start experimenting with dedicated threads, group chats, or other recipients to chase a notification — that's a scope creep this skill explicitly avoids (see Channel priority above; the issue anticipates self-messaging may not notify and treats that as information, not a bug to iterate around).

Bundled scripts

Notes

• This skill does not modify, read, or depend on any watchdog, roster, or supervisor state file. Wiring a caller's escalation logic to this script is a separate change (jonhill90/agent-dotfiles#50).
• Rate-limiting and dedup state live under $NOTIFY_STATE_DIR (~/.local/state/notify by default) — local to the machine, never committed, never read by this repository's validator.