Notifications

Magia notifies you when something in a session needs attention. Notifications appear both inside the app (the bell icon in the navbar) and as native OS notifications when the app window is not focused.

Notification types

There are four notification types, each with a distinct icon and color:

Type	Icon	Color	When used
attention	Warning triangle	Amber	Agent is waiting for permission approval
error	Circle X	Red	Session error or session ended with an error
completed	Circle check	Green	Agent finished its turn, ready for input
info	Info circle	Blue	General informational messages

Events that trigger notifications

The following agent events are mapped to notifications:

Agent event	Notification type	Title
turn.ended	completed	”Agent finished”
session.error	error	”Session Error”
session.ended (with error)	error	”Session Error”
permission.requested	attention	”Permission Required”

session.ended without an error does not produce a notification (the preceding turn.ended already covers the completed state).

In-app notification panel

Click the bell icon in the navbar to open the notification panel. It shows all active (non-dismissed) notifications sorted by most recent first. Unread notifications have a highlighted background. The bell icon shows an unread count badge when there are unread items.

Each notification entry shows:

• The notification type icon.
• The provider icon (if the session is tied to a specific LLM provider).
• Title and optional message body.
• Project name and session name as breadcrumb context.
• A relative timestamp (“2 minutes ago”).

Click a notification to mark it as read and navigate directly to the associated session. If the notification has no sessionId, clicking marks it as read without navigation.

Dismiss (the X button on hover) removes the notification from the panel permanently.

Mark all as read clears the unread count in one click.

Native OS notifications

Native notifications are sent via @tauri-apps/plugin-notification when:

1. The app window is not focused at the time the event arrives.
2. Desktop notifications are enabled (desktopNotificationsEnabled).
3. OS notification permission is granted (Magia requests it on first use).

The native notification title includes the project name (e.g., “Agent finished — my-project”). The body includes the project name, session name, and event message.

Duplicate events for the same session within a 3-second window are deduplicated to prevent double notifications from stale connections.

Granular settings

Navigate to Settings → Notifications to configure:

Setting	Default	Description
Enable notifications	On	Master switch; disables all notifications when off
Session completed	On	turn.ended and non-error session.ended
Session error	On	session.error and error session.ended
Agent waiting	On	permission.requested
System updates	On	App update alerts
Sound	On	Play a sound with each notification
Desktop notifications	On	Send native OS notifications when unfocused

Turning off the master switch overrides all granular settings. Individual toggles only apply when the master switch is on.