@pi-unipi/notify

@pi-unipi/notify

Push notifications when things happen. Workflow finishes, Ralph loop completes, MCP server errors — notify sends alerts to native OS, Gotify, Telegram, or ntfy.

Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify. Native desktop notifications can also be suppressed while the Pi window is focused.

Commands

Command	Description
/unipi:notify-settings	Open settings overlay to configure platforms and events
/unipi:notify-set-gotify	Configure Gotify server connection
/unipi:notify-set-tg	Interactive Telegram bot setup
/unipi:notify-set-ntfy	Configure ntfy topic and server
/unipi:notify-recap-model	Set model for notification recaps
/unipi:notify-test	Send test notification to all enabled platforms

Special Triggers

Notify subscribes to Pi lifecycle events and routes notifications based on your config:

Event	Default	Description
workflow_end	On	Workflow command completes
ralph_loop_end	On	Ralph loop completes
mcp_server_error	On	MCP server error
agent_end	Off	Agent finishes responding
memory_consolidated	Off	Memory auto-saved
session_shutdown	Off	Session ends

Notify registers with the info-screen dashboard, showing enabled platforms and last notification time. The footer subscribes to NOTIFICATION_SENT events to display notification stats.

Agent Tool

Tool	Description
notify_user	Send cross-platform notification

notify_user({
  title: "Build Failed",
  message: "TypeScript compilation failed with 12 errors.",
  priority: "high"
})

Platforms

Native OS

Desktop notifications via node-notifier:

• Windows: SnoreToast (no admin required)
• macOS: terminal-notifier
• Linux: notify-send / libnotify

Zero configuration — works out of the box. Set native.suppressWhenFocused to true to skip native notifications when the active/focused window is already Pi.

Gotify

Self-hosted push notification server:

{
  "gotify": {
    "enabled": true,
    "serverUrl": "https://your-gotify-server.com",
    "appToken": "your-app-token",
    "priority": 5
  }
}

Telegram

Bot API notifications. Run /unipi:notify-set-tg for interactive setup:

1. Create a bot via @BotFather
2. Paste the bot token
3. Auto-detect your chat ID

ntfy

HTTP-based pub-sub notifications via ntfy.sh or self-hosted:

{
  "ntfy": {
    "enabled": true,
    "serverUrl": "https://ntfy.sh",
    "topic": "your-topic-name",
    "priority": 3
  }
}

Configurables

Settings stored at ~/.unipi/config/notify/config.json. Edit via /unipi:notify-settings or manual JSON editing.

Per-event platform routing lets you control where each event type goes. The settings overlay shows all events with platform toggles.

License

MIT