@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