Notification troubleshooting

Solo sends both in-app toasts and native desktop notifications depending on the situation. If notifications aren't showing up, work through these checks in order.

Check 1: Verify Solo's notification status#

1. Open Settings > Notifications. By default, press Cmd+, on macOS or Ctrl+, on Windows/Linux; this shortcut can be changed in Settings > Hotkeys.
2. Check the System notifications status:
   • Enabled — on macOS, Solo has notification authorization. On Windows, Solo reports Enabled without checking Windows notification settings, so verify Windows settings separately if delivery fails.
   • Denied — macOS has denied permission. Click Open system settings.
   • Not requested — macOS has not reported a permission decision. Click Enable notifications to request permission.
   • Provisional — macOS granted provisional delivery. Click Open system settings to review Solo's notification settings.
   • Ephemeral — macOS reported ephemeral authorization. Click Open system settings to review Solo's notification settings.
   • Unavailable — Solo could not access its native notification subsystem. Relaunch Solo; if the status remains Unavailable, report the issue.

Check 2: System permissions#

On macOS, follow the steps below when the status is Denied, Provisional, or Ephemeral. On Windows, check the host settings whenever native delivery fails; Solo's Enabled status does not inspect Windows notification settings.

On macOS:

1. Go to System Settings > Notifications (or System Preferences on older macOS).
2. Find Solo in the app list.
3. Turn on Allow notifications.

On Windows:

1. Go to Settings > System > Notifications.
2. Make sure notifications are enabled.
3. Find Solo in the app notification list and allow notifications.

If Solo does not appear in the macOS list and the status is Not requested, click Enable notifications in Solo's Notification settings to request permission. That button requests macOS permission only; on Windows, use Windows notification settings.

Check 3: Focus or do-not-disturb mode#

Focus modes and do-not-disturb settings can silently suppress notifications from all or specific apps.

On macOS:

1. Check the Control Center or Focus menu to see if a Focus mode is active.
2. If one is active, add Solo as an allowed app:
   • Go to System Settings > Focus > [Your Focus Mode] > Allowed Notifications > Apps.
   • Add Solo.

On Windows:

1. Open Settings > System > Notifications.
2. Check Do not disturb and notification priority settings.
3. Add Solo as an allowed app if do-not-disturb mode is enabled.

Check 4: Send a test notification#

In Settings > Notifications, click Send test.

• If you see the test, the explicit native test path reached a visible notification. A missing process or terminal alert can still be caused by its notification level, focus-aware route, selected-process suppression, or event input.
• If you do not see the test, the result does not isolate one cause. Recheck Solo's status, Focus/Do Not Disturb, and the operating system's per-app presentation settings.

Check 5: Understand focus-aware delivery#

For normal process-crash, terminal, auto-restart-exhaustion, and solo.yml alerts:

• When Solo is focused, the alert appears as an in-app toast.
• When Solo is not focused, the alert is sent as a native notification.
• A terminal alert from the selected process is suppressed while Solo is focused.
• A successful auto-restart remains a transient in-app toast even while Solo is unfocused.

Send test explicitly uses the native channel, and server announcements remain persistent in-app toasts. If you're always looking at the process when events happen, you'll generally get toasts instead of system notifications. That's expected behavior.

Check 6: Notification levels#

Project and process notification levels are combined by taking the more restrictive setting:

• All allows terminal BEL/OSC alerts and important process alerts.
• Important allows crashes and auto-restart-exhausted alerts, but suppresses terminal BEL/OSC alerts.
• None suppresses both terminal alerts and important process alerts.

If a script notification is not appearing, confirm both the project and process allow All.

Check 7: Rate limiting#

Terminal notifications are rate-limited to 5 notifications per 10 seconds per process reader. Auto-restart is also rate-limited: after 10 restarts in 60 seconds, Solo stops retrying and writes an Auto-restart paused banner in the terminal. The separate exhausted UI indicator and notification appear only when the effective notification level is Important or All; at None, Solo does not set or send them.

Check 8: Verify OS notification settings#

Even with permission granted, per-app OS settings can prevent visible presentation.

macOS:

1. Open System Settings > Notifications > Solo.
2. Verify Allow notifications is on.
3. Set alert style to Banners or Alerts.
4. Enable Show in Notification Center.
5. Enable Show on Lock Screen if needed.

Windows:

1. Open Settings > System > Notifications.
2. Find Solo and make sure notifications are on.
3. Expand Solo's settings and verify banners are enabled.
4. Check that Solo is not in any priority-only exclusion list.

Solo requests silent native notification content on macOS and Windows. For audible terminal, crash, and auto-restart-exhaustion alerts on macOS, choose a separate Bell sound in Solo's Notification settings. Solo currently has no corresponding Windows bell-playback branch, so Windows notification-sound settings do not enable Solo alert audio.

Still not working?#

• Fully quit and relaunch Solo. Notification initialization happens at startup.
• On macOS, try signing out and back in to refresh the notification subsystem.
• Report the issue via the command palette and choose Report an issue or share feedback. Solo automatically includes the app version, operating system, and OS version; include the notification event types you're testing and any unusual build or environment details that are relevant.