Desktop notifications for Pi agent via OSC 777/99 and Windows toast
npm install pi-notifyA Pi extension that sends a native desktop notification when the agent finishes and is waiting for input.
| Terminal | Support | Protocol |
|----------|---------|----------|
| Ghostty | ✓ | OSC 777 |
| iTerm2 | ✓ | OSC 777 |
| WezTerm | ✓ | OSC 777 |
| rxvt-unicode | ✓ | OSC 777 |
| Kitty | ✓ | OSC 99 |
| Windows Terminal | ✓ | PowerShell toast |
| Terminal.app | ✗ | — |
| Alacritty | ✗ | — |
``bash`
pi install npm:pi-notify
Or via git:
`bash`
pi install git:github.com/ferologics/pi-notify
Restart Pi.
When Pi's agent finishes (agent_end event), the extension sends a notification via the appropriate protocol:
- OSC 777 (Ghostty, iTerm2, WezTerm, rxvt-unicode): Native escape sequence
- OSC 99 (Kitty): Kitty's notification protocol, detected via KITTY_WINDOW_IDWT_SESSION
- Windows toast (Windows Terminal): PowerShell notification, detected via
Clicking the notification focuses the terminal window/tab.
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.
`fish`
set -Ux PI_NOTIFY_SOUND_CMD 'afplay ~/Library/Sounds/Glass.aiff'
`bash`
export PI_NOTIFY_SOUND_CMD='paplay /usr/share/sounds/freedesktop/stereo/complete.oga'
`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.
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, iTerm2, WezTerm adopted it. Kitty uses 99` with a more extensible protocol.
Terminal multiplexers (zellij, tmux, screen) create their own PTY and typically don't pass through OSC notification sequences. Run pi directly in your terminal for notifications to work.
MIT