pi-notifier

Lightweight macOS desktop notifications for pi.

When pi finishes processing and is ready for your next input, you'll get a native macOS notification. Perfect for when pi is running a long task and you're working in another window.

Current notification format for waitingForInput:

• title: pi-notification-<session_info>
• content: pi 最后一轮输出内容（会自动压缩空白并截断）

Features

• Native macOS notifications via AppleScript (osascript)
• Telegram bot notifications via configurable bot token + chat ID
• Configurable sound - choose from system sounds like Glass, Hero, Ping, Submarine
• Deduplication - prevents notification spam with configurable minimum interval
• Zero dependencies - lightweight, no runtime dependencies required
• Per-project config - override global settings per project

Installation

Quick Test

Load temporarily without installing:

pi --extension /path/to/pi-notifier/extensions/notifier.ts

Install as pi Package

Globally:

pi install /path/to/pi-notifier

Project-local (shareable with your team):

pi install -l /path/to/pi-notifier

Configuration

Create a config file at ~/.pi/agent/pi-notifier.json (global) or .pi/pi-notifier.json (project).

Project config overrides global config.

Example Configuration

{
  "enabled": true,
  "desktop": {
    "enabled": true
  },
  "telegram": {
    "enabled": false,
    "botToken": "123456:your-bot-token",
    "chatId": "123456789"
  },
  "sound": {
    "enabled": true,
    "name": "Glass"
  },
  "events": {
    "waitingForInput": true,
    "waitingForDecision": true
  },
  "dedupe": {
    "minIntervalMs": 2000
  },
  "messages": {
    "waitingForInput": {
      "title": "Pi",
      "body": "Ready for input"
    }
  }
}

注意：waitingForInput 的实际通知标题和正文现在会动态生成。配置里的 messages.waitingForInput.title/body 仅作为无法获取最后一轮输出时的兜底文案。

Configuration Options

Option	Type	Default	Description
enabled	boolean	true	Master switch for all notifications
desktop.enabled	boolean	true	Enable/disable desktop notifications
telegram.enabled	boolean	false	Enable/disable Telegram bot notifications
telegram.botToken	string	undefined	Telegram bot token from BotFather
telegram.chatId	string	undefined	Target chat ID / user ID / group ID
telegram.apiBaseUrl	string	"https://api.telegram.org"	Optional Telegram API base URL override
sound.enabled	boolean	true	Enable/disable notification sound
sound.name	string	"Glass"	System sound name (Glass, Hero, Ping, Submarine, etc.)
events.waitingForInput	boolean	true	Notify when pi is ready for input
events.waitingForDecision	boolean	true	Notify when waiting for user decision (future use)
dedupe.minIntervalMs	number	2000	Minimum ms between notifications
messages.waitingForInput.title	string	"Pi"	Fallback title only; normal waitingForInput notifications use pi-notification-<session_info>
messages.waitingForInput.body	string	"Ready for input"	Fallback body only; normal waitingForInput notifications use the last Pi output

Commands

Test Notification

Send a test notification to verify your configuration (desktop and/or Telegram):

/pi-notifier-test
/pi-notifier-test decision

Show Status

Display current configuration and effective settings:

/pi-notifier-status

How It Works

waitingForInput

Triggered when pi's agent finishes processing (via the agent_end event). This is the primary use case: you start a long-running task, switch to another app, and get notified when pi is ready for your next instruction.

For this event, the notifier now builds the message dynamically:

• title = pi-notification-<session_info>
• body = the last assistant output from Pi

If no assistant output can be extracted, it falls back to the configured messages.waitingForInput.body value.

waitingForDecision

This release includes the configuration and message structure for decision notifications, but does not automatically intercept other extensions' dialogs. Future versions may provide a helper function that extensions can call when awaiting user decisions.

Sound Notes

Sound playback is best-effort. macOS may ignore the requested sound based on:

• System notification permissions
• Notification Center settings for the app
• Whether the sound name is recognized

Common system sounds: Glass, Hero, Ping, Submarine, Pop, Purr, Blow, Bottle

Telegram Setup

1. Create a bot with @BotFather and copy the bot token
2. Start a chat with the bot (or add it to a group)
3. Obtain the target chatId
   • personal chat usually is your numeric user ID
   • group chat usually is a negative number
4. Add the config:

{
  "telegram": {
    "enabled": true,
    "botToken": "123456:your-bot-token",
    "chatId": "123456789"
  }
}

When enabled, notifier sends:

pi-notification-<session_info>
<last assistant output>

Limitations

• Desktop notifications are macOS only (uses AppleScript)
• Telegram notifications require outbound network access and valid bot permissions
• No click-to-focus action (notification is informational only)
• Does not globally intercept all extension dialogs

Requirements

• macOS
• pi installed

License

MIT

Acknowledgments

Inspired by the notify.ts example from the pi-mono project.