@pedro_klein/pi-alert

System notifications for Pi agent completion and configured tool calls

Packages

Package details

extension

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

npm repohome report
$ pi install npm:@pedro_klein/pi-alert
Package
@pedro_klein/pi-alert
Version
0.2.1
Published
Oct 5, 2026
Downloads
291/mo · 9/wk
Author
pedro_klein
License
MIT
Types
extension
Size
70.1 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

pi-alert

System notifications for Pi. It alerts when an agent run finishes and when a configured tool starts.

Install

pi install npm:@pedro_klein/pi-alert

Tool alerts

Add tool names and notification messages under pi-alert.toolAlerts in ~/.pi/agent/settings.json:

{
  "pi-alert": {
    "toolAlerts": {
      "ask_user": "Waiting for your answer",
      "approval_gate": "Approval required"
    }
  }
}

Trusted project settings in .pi/settings.json can add or override entries. Invalid values are ignored. Reload Pi after changing settings.

Tool alerts fire on tool_execution_start, before the tool executes. Agent completion notifications continue to fire on agent_end and summarize elapsed time and tool activity.

Notification delivery

Delivery is terminal-first, with an operating-system fallback:

  • Ghostty on macOS: native Notification Center delivery through Ghostty
  • Ghostty on other platforms, WezTerm, and rxvt-unicode: OSC 777
  • iTerm2: OSC 9
  • Kitty: OSC 99
  • tmux: passthrough to supported outer terminals
  • macOS: osascript
  • Linux: notify-send
  • Windows: PowerShell notification
  • Final fallback: terminal bell

Development

pnpm --filter @pedro_klein/pi-alert test
pnpm --filter @pedro_klein/pi-alert typecheck
pnpm --filter @pedro_klein/pi-alert build

Attribution

Derived from maxpetretta/pi-alert, copyright Max Petretta, under the MIT License. See LICENSE.