Notifications
When a block or stack fails to load, parse, or validate, Stackie records the diagnostic as a notification. One notification, three surfaces — all driven by the same diagnostic pipeline so the message stays consistent wherever you see it.
The three surfaces
| Surface | What you see | When it fires |
|---|---|---|
| Dashboard bell (top bar) | Unread count badge + a deep-link list to the offending block’s Definition tab | Always, while the dashboard is open or via SSE when it next opens |
| Tray menu label | View Dashboard (🔔 N) on macOS, View Dashboard (N) on Linux / Windows | Always, refreshed on every tray update tick |
| OS notification centre | macOS Notification Centre, Windows toast, or Linux libnotify | On the first insertion of a diagnostic in the dedupe window (5 s); repeats are silent |
The OS surface is the loudest of the three — it can pull you out of an editor or another desktop — so Stackie defaults to a conservative filter: only errors raise a toast, and only when the user has not opted out.
Privacy note: notification bodies quote the diagnostic message verbatim, which can include block names, file paths, and parser-echoed YAML fragments from your stack files. macOS Notification Centre and Windows Action Centre persist these in user-readable history. Treat them like log output — if you’re screen-sharing or projecting, disable OS notifications for the session via the setting below.
Settings
Configure both behaviours in ~/.stackie/settings.yml under the
notifications block:
notifications:
retention_days: 7 # how long to keep notifications in the dashboard feed
os_notifications_enabled: true # surface new failures via the OS notification centre
os_notifications_min_severity: error # "error" or "warning"The dashboard’s Settings → Notifications form exposes all three fields with the same defaults.
os_notifications_enabled
Defaults to true. Set to false to turn off OS-level toasts entirely while
keeping the dashboard bell and tray badge — useful if you keep the dashboard
open all day and find the toasts duplicative.
The setting is enforced at the service boundary: when disabled, Stackie does
not call into the OS notification API at all, so it never burns the per-app
rate limit your OS imposes (Linux org.freedesktop.Notifications is
particularly strict).
os_notifications_min_severity
Defaults to error. Lower it to warning if you want toasts for warnings
too. Filtering happens before the OS call, same reasoning as the enabled
flag.
retention_days
Notifications older than this are deleted automatically. Defaults to 7 days,
capped at 3650 (10 years). Setting 0 does not disable the purge — it
makes every notification eligible for deletion on the next purge tick (within
an hour). To pause purging, raise the value to a high number like 36500.
Dedupe behaviour
A single misbehaving block can emit the same diagnostic many times during a hot-reload loop. Stackie coalesces repeats so you do not get flooded:
- The first occurrence inserts a row, fires SSE, and (if enabled) raises an OS notification.
- Subsequent occurrences within 5 seconds with the same
(code, source_file, line, column)are silently dropped.
This applies to all three surfaces equally — the OS notification fires only on the first insertion.
Per-platform behaviour
| Platform | OS notification backend | Notes |
|---|---|---|
| macOS | NSUserNotification via mac_notification_sys (the Cocoa API used by notify-rust 4.x) | No permission prompt; titles and bodies are passed as NSString, so YAML content from your stacks cannot inject AppleScript. |
| Windows | WinRT ToastNotificationManager | Reuses stackied’s existing AppUserModelID (set up for the tray icon — no extra registration needed). |
| Linux | org.freedesktop.Notifications over D-Bus (libnotify) | On headless dev boxes without a notification daemon, the dispatch silently fails (Stackie logs at debug level); the dashboard bell and tray badge still work. |
Where to look when a notification fires
- Click the OS toast (where the platform supports it) → opens the dashboard at the offending block’s Definition tab.
- Click the dashboard bell → list of all unread notifications, each one deep-links to the relevant Definition tab with the YAML span highlighted.
- Click the tray menu →
View Dashboard (🔔 N)opens the dashboard with the same deep-link.
For more detail on reading the diagnostic itself (codes, spans, hints) see Reading Validation Errors.