pi-notify

Desktop notifications for Pi agent via OSC 777/99/9 and Windows toast

Package details

← Back
extension

Install pi-notify from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-notify
Package
pi-notify
Version
1.3.0
Published
Feb 10, 2026
Downloads
458/mo · 100/wk
Author
ferologics
License
MIT
Types
extension
Size
10 MB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "index.ts"
  ],
  "video": "https://raw.githubusercontent.com/ferologics/pi-notify/master/demo.mp4"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-notify

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

pi-notify demo

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 ✓ PowerShell toast
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
  • Windows toast (Windows Terminal): PowerShell notification, detected via WT_SESSION

Clicking the notification focuses the terminal window/tab.

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