pi-notifications

Terminal notifications for Pi: OSC 99 / OSC 777 content channels.

Shows notifications for Pi lifecycle events (turns, tools, subagents, permission prompts, MCP failures) via terminal escape sequences (OSC 99 for Kitty / VS Code, OSC 777 for Ghostty / fallback) or a Herdr local toast.

Install

pi install npm:@ceski23/pi-notifications

Restart Pi after installation.

• Settings UI: /pi-notifications:settings — a native Pi-style modal (mirrors Pi's own /settings: separator lines, searchable list, boolean cycling, separate selection/editor views for enums and text/numbers), backed by @zigai/pi-extension-settings.
• Design and channel protocol details: SPEC.md.

Configuration

Global settings are stored in ~/.pi/agent/extension-settings/pi-notifications.json.

| Option | Type | Default | Description | | --- | --- | --- | --- | | enabled | boolean | true | Master switch for terminal notifications | | onlyWhenInteractive | boolean | true | Suppress notifications when Pi has no UI | | progress | boolean | true | Update the working toast with turn/tool/elapsed stats each turn | | backend | auto | osc99 | osc777 | herdr | "auto" | Delivery backend — terminal escape (OSC) or herdr toast | | extSubagents | boolean | true | Notify on subagent lifecycle events (@tintinweb/pi-subagents) | | extPermissions | boolean | true | Notify when the permission UI is invoked (@gotgenes/pi-permission-system) | | extRpiv | boolean | true | Notify before an ask-user question dialog (@juicesharp/rpiv-ask-user-question) | | extMcp | boolean | true | Notify when an MCP server status becomes failed or needs auth (pi-mcp-adapter) |

{
  "$schema": "./schemas/pi-notifications.schema.json",
  "enabled": true,
  "onlyWhenInteractive": true,
  "progress": true,
  "backend": "auto",
  "extSubagents": true,
  "extPermissions": true,
  "extRpiv": true,
  "extMcp": true
}