Notifications

Superagent sends notifications when agents need your attention or when automated tasks fire. Notifications appear as OS-level alerts (desktop banners or browser notifications) and are also stored in an in-app notification center with read/unread tracking.

Notification types

There are five notification types, each triggered by a different kind of agent event:

Session complete

Triggered when an agent finishes running a session. The notification reads something like "Research Agent has finished running". This type is suppressed for automated sessions (scheduled tasks, webhook triggers, and chat integrations) since those are not user-initiated and would create noise.

Session waiting (action required)

Triggered when an agent is blocked and needs user input. This is the most important notification type because the agent cannot continue without you. The waiting reason is included in the notification body:

A special variant of this type is the API request review notification. When an agent makes an API call that requires user approval (based on scope policies), the notification includes Approve and Deny action buttons on macOS. Clicking a button submits the review decision without needing to open the app.

Session scheduled

Triggered when a scheduled task starts a new session. The notification reads something like "Daily report started for Research Agent".

Session webhook

Triggered when a webhook trigger fires and starts a new session. The notification reads something like "GitHub push trigger fired for DevOps Agent".

Session chat integration

Triggered for chat integration lifecycle events (connected, disconnected, or error). These are informational and do not require user action.

User-actionable vs. informational

Superagent distinguishes between actionable and informational notifications for badge counting:

• Actionable: session_complete and session_waiting. These contribute to the unread count badge and the sidebar's unread indicators.
• Informational: session_scheduled, session_webhook, and session_chat_integration. These appear in the notification history but do not increment the unread badge.

This distinction prevents automated events from creating a false sense of urgency. A webhook that fires 50 times a day should not bury the one notification where an agent actually needs your help.

The notification center

The notification center is a dedicated view accessible from the sidebar. It shows a chronological list of all notifications with:

• Agent name and slug suffix for identification
• Title and body text summarizing the event
• Timestamp in a relative format (e.g., "2:30 pm" for today, "yesterday", "May 12" for older)
• Unread indicator as a blue dot on the left edge

Clicking a notification navigates you to the relevant session (or to the agent home for chat integration events) and automatically marks it as read.

Bulk actions

A Mark all as read button at the top clears all unread indicators at once. This is useful after reviewing a backlog of notifications.

Session-level read tracking

When you open a session, all notifications for that session are automatically marked as read. This means you do not need to manually dismiss individual notifications for a session you are already looking at.

Pagination

The notification center is paginated (15 items per page) with total count displayed. Older notifications beyond the current page are still accessible through pagination controls.

Notification settings

Notification preferences are configured in Settings > Notifications. Each user has independent settings.

Global toggle

The master Enable Notifications switch controls whether any notifications are shown. When disabled, no OS notifications or in-app notifications are created.

Per-type toggles

When the global toggle is on, you can individually enable or disable:

• Session Complete --- When an agent finishes running
• Action Required --- When an agent needs input (secrets, account access, API review)
• Scheduled Task Started --- When a scheduled task begins running

Browser permission

In the web interface (non-Electron), browser notification permission is required for OS-level alerts. If permission has not been granted, the settings page shows a prompt to request it. If permission was denied in the browser, the settings page explains how to re-enable it in browser settings.

Test notification

A Send Test button lets you verify that notifications are working. In the Electron app, this also triggers the macOS notification permission prompt if it has not been shown yet.

OS notification delivery

Superagent delivers OS notifications differently depending on the runtime:

Electron (desktop app)

Uses Electron's native notification API, which supports macOS notification actions (Approve/Deny buttons for API reviews). The dock badge count is synced with the unread notification count. Notifications that arrive while the renderer is not loaded are queued and replayed when the window opens.

Web browser

Uses the standard Web Notifications API. Action buttons are not supported in web notifications --- clicking the notification focuses the browser window and navigates to the relevant session. Notifications are only shown if the user has granted browser notification permission.

Smart suppression

Notifications are suppressed when you are already looking at the relevant session. The specific suppression logic differs by notification type:

• Action-required notifications (session_waiting) are only suppressed if both the tab is visible and the window has focus. This ensures you still get alerted if the app is visible but you are working in another application.
• All other notifications are suppressed whenever the tab is visible, even if the window is not focused. This avoids unnecessary interruptions for informational events.

Auth mode behavior

In auth mode, notifications are scoped to the agents each user has access to:

• Users only see notifications for agents they have been granted access to (via agent ACLs).
• The unread count badge reflects only notifications for accessible agents.
• The SSE notification stream filters events by agent access, so users never receive real-time events for agents they cannot see.
• Admins are not exempt from scoping --- they see notifications for agents explicitly shared with them, matching the agent list behavior.

Notification settings are per-user. In non-auth mode, a single set of settings controls notification behavior for all sessions. In auth mode, the server always creates the notification (since settings are per-client), and each connected client independently checks its own user's preferences before showing the OS alert.

Data retention

Notifications older than 30 days are automatically cleaned up. The cleanup runs periodically and removes both read and unread notifications past the retention window.