@pi-lab/notify

Desktop notification extension for pi coding agent.

Install

pi install npm:@pi-lab/notify

Behavior

This extension sends a notification for two events:

• agent_settled — title Pi, message Ready for input
• permissions:ask — title Pi, message Permission required: <toolName>

permissions:ask is emitted by @pi-lab/permissions immediately before a permission prompt is shown.

When Pi runs inside tmux, each notification also emits a terminal bell. For a background window, tmux marks and highlights its window label until the window is selected. This requires tmux's monitor-bell window option, which is enabled by default. The highlight uses window-status-bell-style and can be customized in ~/.tmux.conf:

setw -g monitor-bell on
set -g window-status-bell-style 'fg=yellow,bold'

Notification backend

The built-in notification backend is auto-detected:

• Windows Terminal / WSL: PowerShell toast
• Kitty: OSC 99
• Other terminals: OSC 777

Click handling is not implemented by the built-in backend. Use the script hook for terminal- or OS-specific click behavior.

Configuration

Set the notify object in pi settings:

• Global: ~/.pi/agent/settings.json
• Local: <cwd>/.pi/settings.json

Local config overrides global config field by field.

Disable built-in notifications

{
  "notify": {
    "enable": false
  }
}

enable defaults to true and controls built-in desktop notifications and tmux window alerts. Script hooks still run when enable is false.

Script hook

{
  "notify": {
    "script": "~/.pi/agent/pi-lab/notify.sh"
  }
}

When configured, the script is executed for every notify event in addition to the built-in notification. The script receives a JSON payload on stdin and has a fixed 5 second timeout. Failures are warned in Pi and do not affect agent execution or permission prompts.

Example payload for agent_settled:

{
  "event": "agent_settled",
  "notificationId": "pi-agent-settled-1778220000000",
  "title": "Pi",
  "message": "Ready for input",
  "timestamp": 1778220000000,
  "cwd": "/home/user/project",
  "pid": 12345,
  "terminal": {
    "term": "xterm-kitty",
    "termProgram": "kitty",
    "kittyWindowId": "1"
  }
}

Example payload for permissions:ask:

{
  "event": "permission_ask",
  "notificationId": "pi-permission-ask-1778220000000",
  "title": "Pi",
  "message": "Permission required: bash",
  "timestamp": 1778220000000,
  "cwd": "/home/user/project",
  "pid": 12345,
  "terminal": {
    "term": "xterm-kitty",
    "termProgram": "kitty",
    "kittyWindowId": "1"
  }
}

Unavailable terminal fields are omitted from the JSON sent to the script.

The script payload intentionally does not include raw tool input, permission rules, options, or tool call identifiers.

Example script:

#!/usr/bin/env bash
set -euo pipefail
payload="$(cat)"
message="$(jq -r .message <<<"$payload")"
notify-send "Pi" "$message"