Notifications

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, reading something like "Research Agent has finished running". This type is suppressed for automated sessions (scheduled tasks, webhook triggers, and chat integrations), which 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 type because the agent cannot continue without a response. The waiting reason is included in the notification body:

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

Session scheduled

Triggered when a scheduled task starts a new session, reading something like "Daily report started for Research Agent".

Session webhook

Triggered when a webhook trigger fires and starts a new session, reading 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 require no action.

User-actionable vs. informational

For badge counting, Gamut distinguishes actionable from informational notifications:

• 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 inbox but do not increment the unread badge.

This 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 help.

The notification inbox

All notifications land in a merged inbox, accessible from the sidebar, listing every agent's alerts chronologically:

• 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

Each notification has a detail view. Opening it marks the notification read and links through to the relevant session (or the agent home for chat integration events).

Bulk actions

A Mark all as read button at the top clears all unread indicators at once, useful after reviewing a backlog.

Session-level read tracking

Opening a session marks all of its notifications as read, so notifications for a session already on screen never need manual dismissal.

Pagination

The inbox is paginated (15 items per page) with the total count displayed. Older notifications remain accessible through the pagination controls.

Notification settings

Notification preferences live 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 or in-app notifications are created.

Per-type toggles

When the global toggle is on, each of these can be enabled or disabled individually:

• 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

Notify when window unfocused

The Notify when window unfocused setting controls whether OS notifications are delivered while the app is visible but another window has focus.

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, the settings page explains how to re-enable it in the browser.

Test notification

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

OS notification delivery

Delivery differs by 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 syncs 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; clicking the notification focuses the browser window and navigates to the relevant session. Notifications only appear if browser notification permission has been granted.

Smart suppression

Notifications are suppressed when the relevant session is already on screen. The suppression logic is type-aware:

• Action-required notifications (session_waiting) are suppressed only when the tab is visible and the window has focus. Alerts still fire when the app is visible but another application is in the foreground.
• All other types are suppressed whenever the tab is visible, even without window focus, avoiding interruptions for informational events.

Auth mode behavior

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

• 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 covers all sessions. In auth mode, the server always creates the notification (settings are per-client), and each connected client checks its own user's preferences before showing the OS alert.

Data retention

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