pi-desktop-notifications

A Pi coding agent extension that sends native desktop notifications on macOS and Linux when:

• ✅ A run finishes — the agent completed what was in progress and is ready for next steps. The notification shows the outcome (completed / error / aborted) and a snippet of the agent's final message, so you can see at a glance what happened without switching back to the terminal.
• 💬 The agent needs your input — Pi is blocked mid-run waiting on a dialog (confirmation, choice, text input, editor) raised by an extension.

Zero runtime dependencies. Works in every Pi mode (TUI, RPC, print/JSON) — native notifiers don't need a terminal, so pi -p "long task" from a script notifies too.

Install

Option A — install as a Pi package (recommended)

pi install npm:pi-desktop-notifications

Installs from npm and registers the package in your personal Pi settings (~/.pi/agent/settings.json). Restart Pi or run /reload, then start Pi normally. Pin a version with pi install npm:pi-desktop-notifications@<version> and stay current with pi update --extensions.

Option B — try it in a single session

pi -e npm:pi-desktop-notifications

-e (--extension) loads the package for one invocation without adding it to your settings — nothing is installed or persisted. Swap pi for your usual invocation (e.g. pi -e npm:pi-desktop-notifications -p "long task") to get notified in scripted runs too.

Verify

Start Pi and run:

/notify test

You should see a desktop notification and a confirmation of which backend delivered it.

The /notify command

| Command | Effect | | ----------------------------- | -------------------------------------------------- | | /notify or /notify status | Show enabled state and detected backend | | /notify on / /notify off | Enable/disable for this session | | /notify test [message] | Send a test notification (re-probes for notifiers) |

How it works

Pi fires agent_settled only after a run has fully settled — no automatic retry, compaction, or queued continuation will follow — which is exactly the "ready for next steps" moment. The run outcome comes from agent_before_settle, and the notification body shows the last assistant message. Blocking extension dialogs are covered by ui_prompt_start while a run is active.

Notifications are throttled (default 1.5 s minimum between two) to avoid storms, and a failed backend falls through to the next one — a notification problem can never break the agent.

Notification backends

The first available backend is used; on failure the chain falls through:

| Platform | Order | | -------- | -------------------------------------------------------------- | | macOS | terminal-notifier → osascript → OSC 777/99 terminal escape | | Linux | notify-send → dunstify → OSC 777/99 terminal escape |

• macOS: osascript is built in. Notifications may be attributed to Script Editor and your terminal app must have notification permission (System Settings → Notifications). For nicer attribution, install terminal-notifier (brew install terminal-notifier) — it is picked up automatically.
• Linux: needs libnotify (notify-send) and a notification daemon — GNOME and KDE ship one; wlroots/Hyprland users typically run mako or dunst. Without a daemon, notify-send silently drops the notification; dunstify is used when only dunst is present. If no native backend exists, OSC 777/99 sequences are emitted for supporting terminals (Ghostty, iTerm2, WezTerm, Kitty, rxvt-unicode).

Configuration (environment variables)

| Variable | Default | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------ | | PI_NOTIFY | 1 | Master switch; 0 starts disabled | | PI_NOTIFY_SOUND | Glass | macOS sound name (none or empty to disable) | | PI_NOTIFY_URGENCY | normal | Linux urgency: low, normal, critical | | PI_NOTIFY_PROMPT | 1 | Notify when blocked on an extension dialog; 0 disables | | PI_NOTIFY_ABORT | 0 | Also notify when a run is aborted; set to 1 or true (case-insensitive) to enable | | PI_NOTIFY_MIN_INTERVAL | 1500 | Minimum milliseconds between two notifications; 0 disables the throttle |

Example:

PI_NOTIFY_SOUND=Pop PI_NOTIFY_URGENCY=critical pi

Development

pnpm install
pnpm run check   # typecheck with the real Pi extension types
pnpm run lint    # oxlint — correctness rules on all TS/JS sources
pnpm test        # dependency-free node:test suite (helpers + event flow)
pnpm run fmt     # oxfmt — format the repository in place
pnpm run fmt:check  # verify formatting (the CI gate; run `pnpm run fmt` to fix)

A husky pre-commit hook runs oxfmt and oxlint on staged files on every commit; it installs itself via the prepare script when you pnpm install.

Or use the Nix dev shell, which provides Node (≥ 22.19, as Pi requires), git, pnpm, and the notification tools for your platform (terminal-notifier on macOS, libnotify + dunst on Linux), and runs pnpm install on first entry:

nix develop

If you use direnv, direnv allow once in the repo root loads the same shell automatically whenever you cd in — no nix develop wrapper needed. Supports x86_64-linux, aarch64-linux, and aarch64-darwin (Apple Silicon; nixpkgs 26.11 dropped Intel Mac support).

Then load it directly while iterating:

pi --extension ./index.ts

License

MIT