How to Set Up Alerts in PI Desktop: Toast and Notification Center Implementation

PI Desktop provides two built-in alert mechanisms—transient toast messages via pi.ui.showToast() and persistent notifications via pi.api.notify()—both accessible from JavaScript/TypeScript plugins and core application code.

The alerting architecture in the vastsa/PI-Desktop repository enables both ephemeral user feedback and durable notification tracking. Whether you are building a plugin or modifying core functionality, you can leverage these APIs to communicate status updates, errors, and task completions.

Toast Alerts for Transient User Feedback

Toast alerts deliver short, transient messages that appear at the top-center of the PI Desktop UI. These are ideal for immediate feedback that does not require persistent storage.

Using the UI API from Plugins

Plugins access toast functionality through the SDK's UI module. The pi.ui.showToast() method routes requests through the Electron IPC bridge defined in apps/desktop/electron/main/plugin-runtime.ts, which forwards the call to the main process store.

The underlying store implementation in apps/desktop/src/stores/app-store.ts maintains the showToast method, which inserts toast entries into a global queue managed by the ToastHost component.

Toast Configuration and Accessibility

The toast API accepts a message string and an optional options object:

• variant: Controls visual styling and ARIA roles ("info", "success", "warning", "error")
• duration: Visibility time in milliseconds (defaults to 4000ms for normal messages, 8000ms for errors)

The Toast component in apps/desktop/src/components/Toast.tsx renders each toast with role="status" for informational variants and role="alert" for error or warning variants, ensuring proper screen-reader announcements via aria-live="assertive" regions.

// Plugin toast implementation
import pi from '@pi/desktop/sdk';

// Informational toast (4 second default)
await pi.ui.showToast('Your notes have been saved.', { variant: 'info' });

// Warning toast with custom duration
await pi.ui.showToast('Low disk space – consider cleaning up.', {
  variant: 'warning',
  duration: 8000,
});

// Error toast (appears as ARIA alert, 8 second default)
await pi.ui.showToast('Failed to connect to the model server.', {
  variant: 'error',
});

Notification Center Alerts for Persistent Storage

For alerts that users must acknowledge or reference later, PI Desktop provides a persistent notification system accessible via the bell-icon panel.

Runtime API Implementation

Persistent notifications use the pi.api.notify() method (or runtime-generated events) handled by the plugin-runtime.ts IPC bridge. The App.tsx component subscribes to notification changes via api.onNotificationChanged, ensuring real-time UI updates when new notifications arrive.

The notification state resides in apps/desktop/src/stores/app-store.ts, which maintains a notifications array supporting read/unread tracking, filtering, and detailed view activation.

Notification Payload Structure

Notifications require a structured payload containing:

• id: Unique identifier for the notification
• kind: Event categorization (e.g., "task.failed", "task.completed")
• sessionId and sessionTitle: Contextual task information
• createdAt: ISO timestamp
• readAt: Nullable timestamp for read status
• errorCode: Optional error classification

The NotificationCenter component in apps/desktop/src/components/NotificationCenter.tsx renders these with appropriate ARIA roles—role="alert" for failures and role="status" for informational notifications.

// Core application notification creation
import { api } from './lib/api';

const payload = {
  id: 'task-1234',
  kind: 'task.failed',
  sessionId: 'session-42',
  sessionTitle: 'Summarize document',
  createdAt: new Date().toISOString(),
  errorCode: 'E401',
};

api.notify(payload);

Internal Alert Routing Architecture

Both alert types traverse through specific pathways while maintaining a single source of truth in the application store.

Toast Routing Flow

1. Plugin Call: pi.ui.showToast() → plugin-runtime.ts ("ui.showToast" case)
2. IPC Bridge: Main process receives the event
3. Store Update: apps/desktop/src/stores/app-store.ts showToast method enqueues the message
4. UI Render: ToastHost component animates and displays the toast, auto-dismissing after the configured duration

Notification Routing Flow

1. Creation: pi.api.notify() or backend event → plugin-runtime.ts ("notification" case)
2. State Management: Store updates the notifications array in app-store.ts
3. UI Subscription: App.tsx receives subscription update via api.onNotificationChanged
4. Render: NotificationCenter.tsx displays the item in the bell-icon panel with read/unread indicators

Key Implementation Files

The following files define the complete alerting stack in PI Desktop:

• apps/desktop/src/stores/app-store.ts – Contains showToast method and notifications array state management
• apps/desktop/src/components/Toast.tsx – Renders toast UI with ARIA role assignment (role="status" or role="alert")
• apps/desktop/src/components/NotificationCenter.tsx – Implements the bell-icon panel with filtering, read tracking, and activation handlers
• packages/plugin-sdk/src/index.ts – Exposes pi.ui.showToast to plugin developers
• apps/desktop/electron/main/plugin-runtime.ts – Bridges plugin API calls to the main process via IPC
• apps/desktop/src/App.tsx – Subscribes to api.onNotificationChanged for real-time notification updates

Summary

• PI Desktop offers two distinct alert mechanisms: transient toast messages for immediate feedback and persistent notification center alerts for trackable events.
• Toast alerts use pi.ui.showToast() with configurable variants (info, success, warning, error) and durations, defaulting to 4 seconds (8 seconds for errors).
• Persistent notifications use pi.api.notify() with structured payloads including id, kind, sessionId, and timestamps, stored in apps/desktop/src/stores/app-store.ts.
• Both systems route through apps/desktop/electron/main/plugin-runtime.ts over Electron IPC, ensuring secure communication between plugin sandbox and main process.
• Accessibility is built-in: Toasts and notifications use appropriate ARIA roles (status for info, alert for errors) and live regions for screen-reader support.

Frequently Asked Questions

How do I show a temporary alert from a PI Desktop plugin?

Import the SDK and call pi.ui.showToast() with your message and variant. The method is exposed through packages/plugin-sdk/src/index.ts and routes through the Electron IPC bridge to display the toast at the top-center of the UI.

What is the difference between toast alerts and notification center alerts in PI Desktop?

Toast alerts are transient messages that auto-dismiss after 4–8 seconds and do not persist in the UI, implemented in apps/desktop/src/components/Toast.tsx. Notification center alerts are durable entries stored in apps/desktop/src/stores/app-store.ts that appear in the bell-icon panel and support read/unread tracking until explicitly dismissed.

How long do toast alerts remain visible in PI Desktop?

Default duration is 4000 milliseconds for informational and success toasts, and 8000 milliseconds for error and warning variants. You can override this by passing a duration value (in milliseconds) to the pi.ui.showToast() options object.

Where are notification states stored in PI Desktop?

Notification states persist in the MobX-based application store defined in apps/desktop/src/stores/app-store.ts, specifically within the notifications array. This store handles read/unread status, filtering, and subscription updates consumed by apps/desktop/src/components/NotificationCenter.tsx.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}