@yusukeshib/pi-notify

A pi extension that fires a native macOS notification when the agent finishes a turn and is ready for your input — powered by terminal-notifier.

Stop babysitting a long run. Switch to another window, and pi taps you on the shoulder when it's done.

What you get

┌─────────────────────────────────────────────┐
│  Pi · ✅ done            12s                 │
│  Added retry logic to the upload client …    │
└─────────────────────────────────────────────┘

• Status-aware title — ✅ done or ❌ error, with the elapsed turn time as the subtitle.
• Context in the body — a snippet of the agent's last message, so you know what happened without switching tabs.
• Focus-aware — if your terminal is already the frontmost app (you're watching it), the notification is suppressed. No spam while you read.
• Click to return — clicking the notification activates the terminal pi is running in (via terminal-notifier's -activate) and brings it to the front.
• Graceful fallback — on non-macOS hosts, or when terminal-notifier isn't installed, it falls back to an OSC 777 desktop notification (Ghostty, iTerm2, WezTerm, …).

Install

For the rich macOS path, install terminal-notifier first:

brew install terminal-notifier

Then add the extension:

pi install npm:@yusukeshib/pi-notify

Via git (no npm publish required):

pi install git:github.com/yusukeshib/pi-notify

Try it without installing:

pi -e npm:@yusukeshib/pi-notify

Command

/notify [subcommand]

| Command | Effect | | ----------------------- | --------------------------------------------------------- | | /notify | Show current settings and the active backend | | /notify on / off | Enable / disable notifications | | /notify sound <name> | Set the notification sound (e.g. Glass, Ping) or off| | /notify min <seconds> | Only notify for turns at least this long (default 0) | | /notify focus on/off| Toggle "skip when terminal is frontmost" (default on) | | /notify test | Fire a test notification right now |

Configuration via environment

Defaults can be set with environment variables; the /notify command overrides them for the current session.

| Variable | Default | Meaning | | ----------------------- | ------- | --------------------------------------------- | | PI_NOTIFY_ENABLED | 1 | Set to 0 to start disabled | | PI_NOTIFY_MIN_SECONDS | 0 | Minimum turn duration before notifying | | PI_NOTIFY_SOUND | off | Sound name, or off for silent | | PI_NOTIFY_FOCUS_SKIP | 1 | Set to 0 to always notify, even when focused|

How it works

The extension tracks each turn via pi's lifecycle events: agent_start resets timing, tool_execution_end records whether any tool errored, and message_end captures the agent's last text. On agent_end it composes a status line and hands it to terminal-notifier.

Focus detection asks macOS (System Events) for the frontmost app's bundle id and compares it to the terminal pi is running in — resolved from __CFBundleIdentifier (the bundle id macOS injects into GUI-launched apps, which survives tmux/ssh better than TERM_PROGRAM), falling back to a TERM_PROGRAM lookup.

Only interactive (tui) sessions notify; print and JSON modes are skipped.

License

MIT