pi-notify-phone

English | 简体中文

Send notifications from the Pi coding agent to your phone - task finished, task failed, a question waiting for you, goal events, and reminders you ask the agent to set. Two transports are supported: Bark and ntfy.

Pi finishes a long task  ->  pi-notify-phone  ->  https://api.day.app/...  ->  your phone buzzes

Features

• Two providers: Bark (iOS) and ntfy (iOS, Android, desktop, web). Choose one in config or with /notify provider bark|ntfy.
• Optional encryption: Bark AES-128-CBC or AES-256-GCM request bodies (the official crypto.ts scheme), and self-hosted ntfy AES-256-GCM envelopes that the agent can decrypt back to plain text.
• Automatic or manual: one master switch, one automatic switch, and a switch per scenario. The agent can always send on request as long as the manual scope is on.
• Scenarios: task start / complete / failed / aborted, ask_user_question waiting for an answer, goal start / complete / blocked / paused, background task start / complete / failed, blocking UI prompts, tool errors, reminders. Every scenario has its own switch, and the table below lists the defaults.
• Reminders and scheduled notifications: relative (in 20m), absolute (at 08:30, tomorrow 09:00), and recurring (every 1d), persisted so a restart still delivers them, and claimed per due time so several Pi sessions open at once deliver each reminder once.
• Noise control: minimum run duration, per-scope throttling, duplicate suppression, body length caps, TTL so stale notifications are dropped, and a switch that silences task notifications while a goal is running.

Install

pi install npm:pi-notify-phone

Or straight from the repository:

pi install git:github.com/voorjaar/pi-notify-phone

Or point Pi at a local checkout:

pi -e /path/to/pi-notify-phone/src/index.ts

Install it once. The npm package and the git source are the same extension; loading both makes Pi reject the duplicate tool names.

Setup

Create ~/.pi/agent/pi-notify.json with at least the provider you want to use:

{
  "provider": "bark",
  "bark": { "key": "your-bark-device-key" }
}

Copy config.example.json for the full set of options. Then check it:

/notify status
/notify test

You can also verify delivery without a Pi session:

node scripts/send.ts "pi-notify-phone" "hello" info

Configuration

Config is merged layer by layer, later layers win:

1. built-in defaults
2. ~/.pi/agent/pi-notify.json
3. <project>/.pi/pi-notify.json
4. <project>/.pi/pi-notify.local.json (personal overrides; .pi/ is gitignored)
5. PI_NOTIFY_* environment variables

Invalid values are ignored and reported by /notify status instead of breaking the session.

Scenario scopes (auto.scopes): one switch each. A scenario that only echoes something that just began, or something you can already see on screen, starts off; everything that reports a result starts on.

goal and bg are group names that cover a whole family at once: /notify scope goal off or PI_NOTIFY_AUTO_SCOPES=goal:off switches all four goal scenarios. A config file written before the split that sets "goal": false (or "bg": true) in auto.scopes is still honoured for the whole group, and a scenario named in the same layer wins over the group. In PI_NOTIFY_AUTO_SCOPES, both noquestion and question:off are accepted, and an unknown name drops the whole override rather than applying half of it.

One blocking ask_user_question arrives as both question and ui_prompt_start. The question notification covers the dialog, so no separate ui_prompt push follows it.

Environment overrides (they win over the files): PI_NOTIFY_PROVIDER, PI_NOTIFY_ENABLED, PI_NOTIFY_TITLE, PI_NOTIFY_STATUS_COLOR, PI_NOTIFY_AUTO_ENABLED, PI_NOTIFY_AUTO_SCOPES=question:off,goal:off, PI_NOTIFY_MIN_RUN_SECONDS, PI_NOTIFY_GOAL_MIN_SECONDS, PI_NOTIFY_SUPPRESS_TASK_NOTIFY, PI_NOTIFY_THROTTLE_SECONDS, PI_NOTIFY_BARK_KEY (comma-separated for several devices), PI_NOTIFY_BARK_BASE_URL, PI_NOTIFY_BARK_GROUP, PI_NOTIFY_BARK_SOUND, PI_NOTIFY_BARK_ICON, PI_NOTIFY_BARK_ENCRYPT, PI_NOTIFY_BARK_ENCRYPT_KEY, PI_NOTIFY_BARK_ENCRYPT_IV, PI_NOTIFY_BARK_ENCRYPT_ALGORITHM, PI_NOTIFY_NTFY_SERVER, PI_NOTIFY_NTFY_TOPIC, PI_NOTIFY_NTFY_TOKEN, PI_NOTIFY_NTFY_USER, PI_NOTIFY_NTFY_PASSWORD, PI_NOTIFY_NTFY_ENCRYPT, PI_NOTIFY_NTFY_ENCRYPT_KEY.

Use it from the agent

Ask in plain language:

• "remind me to stretch in 20 minutes"
• "notify me when the build finishes"
• "ping me every day at 09:30 that the backup ran"

The agent uses the notify tool (in, at, every, level, url, group, sound) and notify_reminders to list, cancel, or clear scheduled notifications. notify_status tells the agent how notifications are configured - provider, switches, pending reminders, and the last sends - so it can tell you whether a notification is actually on its way.

Commands

/notify                        status summary
/notify on | off               master switch (this session)
/notify auto on | off          automatic scenario notifications
/notify scope <name> on|off    one scenario, or a group (`goal`, `bg`)
/notify tasknotify on|off        suppress task notifications while a goal is running
/notify provider bark|ntfy     transport (this session)
/notify test                   send one notification to check delivery
/notify send <text>            send now
/notify schedule <when> <text> [every <dur>]  e.g. /notify schedule 09:30 standup every 1d
/notify list                   scheduled notifications
/notify cancel <id>            cancel one
/notify clear                  cancel all
/notify mute [minutes]         pause automatic notifications (default 30)
/notify unmute                 resume them
/notify log [n]                last n send attempts (sent, skipped, failed)
/notify decrypt <text>         decrypt a pi-notify ntfy envelope

Overrides from /notify apply to the current session; edit the config file to make them permanent.

Encryption

Bark. The extension sends the same envelope the official Bark app produces: ?c=1&zone=... plus a base64 body, where the payload is key:body (or title:body:sound:link:group:icon:call:level) encrypted with AES-128-CBC or AES-256-GCM. The ciphertext is padded to a multiple of 16 bytes, as Bark requires. Set the same key (and IV for AES-128-CBC) in the Bark app under Encryption.

ntfy. Public ntfy.sh topics are plain HTTPS - anything published there is readable by whoever knows the topic. For real confidentiality use a self-hosted ntfy with cache-enc-key and set ntfy.encryption.enabled = true: the extension publishes a pi-notify:v1:<iv>:<tag>:<ciphertext> envelope (AES-256-GCM, key derived from your passphrase with PBKDF2-SHA256) that only a client holding the passphrase can read. /notify decrypt and the agent can turn such an envelope back into readable text.

Development

node --test tests/selftest.ts

The self-test covers time parsing, config layering, both transports, both encryption paths, reminder scheduling, and the notification switches. It uses a fake transport, so it never sends real notifications.

Two live checks drive real Pi sessions and read the delivered notifications back from the send log:

node tests/livecheck.mjs --local              # goal and run-end lifecycle
node tests/live-schedule-dedupe.mjs --local   # reminders across several sessions at once

live-schedule-dedupe.mjs keeps its schedule store and log inside a scratch project and runs with the transport switched off, so it is quiet; its final round re-enables it and delivers one real reminder.

Limitations

• Notifications only fire while a Pi session is running; there is no daemon. A reminder due while Pi is closed is delivered the next time a session starts (or, if it is more than maxLateMs late, skipped: a one-shot is dropped and a recurring one moves to its next occurrence).
• Reminders are delivered by whichever session fires first. Several sessions sharing one schedule file arm the same reminder, so the due time is claimed before the send and only one session delivers it.
• ntfy server-side scheduling (Send At) is used for one-shot reminders when encryption is off; recurring reminders are scheduled by the extension itself.
• The extension does not read your phone, so it cannot tell you whether a notification was actually delivered.

Changelog

Release notes for every version are in CHANGELOG.md.

License

MIT. See LICENSE.

Source, issues, and releases: github.com/voorjaar/pi-notify-phone.