pi-notify

A Pi extension that sends a native desktop notification when the agent finishes and is waiting for input.

Compatibility

Terminal	Support	Protocol
Ghostty	✓	OSC 777
iTerm2	✓	OSC 9
WezTerm	✓	OSC 777
rxvt-unicode	✓	OSC 777
Kitty	✓	OSC 99
tmux (inside a supported term)	✓*	tmux passthrough + OSC 777/99/9
Windows Terminal 1.26+	✓	OSC 777
Terminal.app	✗	—
Alacritty	✗	—

* tmux requires passthrough enabled in your tmux config:

set -g allow-passthrough on

Install

pi install npm:pi-notify

Or via git:

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

Restart Pi.

How it works

When Pi's agent finishes (agent_end event), the extension sends a notification via the appropriate protocol:

• OSC 777 (Ghostty, WezTerm, rxvt-unicode): Native escape sequence
• OSC 9 (iTerm2): iTerm2 notification protocol, detected via TERM_PROGRAM=iTerm.app
• OSC 99 (Kitty): Kitty's notification protocol, detected via KITTY_WINDOW_ID
• tmux passthrough: OSC sequences are wrapped automatically when TMUX is set
• OSC 777 (Windows Terminal 1.26+): detected via WT_SESSION

Clicking the notification focuses the terminal window/tab.

Windows Terminal

Needs Windows Terminal 1.26+ (currently Preview):

winget install --id Microsoft.WindowsTerminal.Preview --exact --source winget

Then turn on notifications in Preview's settings JSON (in profiles.defaults or your Pi profile):

"compatibility.allowOSC777": true

Clicking a notification jumps to the tab that sent it.

If clicking also opens an extra window, turn off Run this profile as Administrator for that profile, then reopen Preview normally.

Optional: Custom sound hook

You can run a custom command whenever a notification is sent by setting PI_NOTIFY_SOUND_CMD.

This keeps the extension tiny and cross-platform: you choose the command for your OS.

Note: This is an additional sound hook. It does not replace native terminal/system notification sounds.

Example (macOS)

set -Ux PI_NOTIFY_SOUND_CMD 'afplay ~/Library/Sounds/Glass.aiff'

Example (Linux)

export PI_NOTIFY_SOUND_CMD='paplay /usr/share/sounds/freedesktop/stereo/complete.oga'

Example (Windows PowerShell)

$env:PI_NOTIFY_SOUND_CMD = 'powershell -NoProfile -Command "[console]::beep(880,180)"'

The command is run in the background (shell: true, detached) so it won't block Pi.

What's OSC 777/99/9?

OSC = Operating System Command, part of ANSI escape sequences. Terminals use these for things beyond text formatting (change title, colors, notifications, etc.).

777 is the number rxvt-unicode picked for notifications. Ghostty and WezTerm adopted it. iTerm2 uses 9 instead, and Kitty uses 99 with a more extensible protocol.

Known Limitations

• tmux works only with passthrough enabled (set -g allow-passthrough on).
• zellij/screen are still unsupported for OSC notifications.

License

MIT