pi-alert

Pi extension that sends a system notification when the agent ends its turn

Package details

← Back
extension

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

npm repohome report
$ pi install npm:pi-alert
Package
pi-alert
Version
0.2.0
Published
Mar 22, 2026
Downloads
111/mo · 32/wk
Author
maxpetretta
License
MIT
Types
extension
Size
21 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/alert.ts"
  ]
}

Security note

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

README

pi-alert

A pi extension that sends a system notification when the agent ends its turn.

Install

pi install npm:pi-alert

Or from GitHub:

pi install git:github.com/maxpetretta/pi-alert

Usage

Install the extension and notifications will fire automatically whenever the agent finishes responding to a prompt.

Notifications use the project root directory in the title (for example pi — pi-alert) and include an activity summary with elapsed time in the body.

Alert text prioritizes the most useful activity summary from the completed run:

  • updated files
  • other tool calls
  • read files
  • generic completion fallback

Notification delivery is terminal-first, with OS fallback:

  • Ghostty, WezTerm, and rxvt-unicode: OSC 777 terminal notifications
  • iTerm2: OSC 9 terminal notifications
  • Kitty: OSC 99 terminal notifications
  • tmux: supported via passthrough to supported outer terminals
  • macOS fallback: osascript with a native notification and the Glass sound
  • Linux fallback: notify-send from libnotify
  • Windows fallback: PowerShell and a System.Windows.Forms.NotifyIcon balloon notification
  • Final fallback: terminal bell (BEL) when no notification transport succeeds

Platform support

Platform Terminal-native notifications Fallback
macOS Yes, in supported terminals such as Ghostty, iTerm2, WezTerm, Kitty, and rxvt-unicode osascript
Linux Yes, in supported terminals such as Ghostty, WezTerm, Kitty, and rxvt-unicode notify-send
Windows Not the primary path today PowerShell balloon notification

Terminal-native notifications require pi to be running inside a supported TTY terminal with the expected environment variables available. When running inside tmux, pi-alert attempts to detect the outer client terminal and forwards notifications through tmux passthrough when allow-passthrough is enabled. If tmux passthrough is unavailable or no supported terminal transport is detected, pi-alert falls back to the platform notification command, and finally to a terminal bell when no notification command succeeds.

Linux notes

Most desktop Linux setups already have notify-send. If yours does not, install it with your distro package manager.

Examples:

sudo apt install libnotify-bin
sudo dnf install libnotify
sudo pacman -S libnotify

Development

This package uses Bun for local development.

bun install
bun run lint
bun run typecheck
bun test

The test suite uses Bun's built-in test runner and covers the platform-specific notification command builders and escaping helpers.

License

MIT