Notifications

Notification banners (transient popups) and the notification center.

Section: [notifications]

Key	Type	Default	What it does
daemon	"auto" / "wam-shell" / "system"	"auto"	Whose notification daemon is used: auto defers to a running system daemon (swaync, dunst, …) and otherwise uses wam-shell's; "wam-shell" forces ours; "system" forces the system's even when none is running (nothing displays notifications then)
popups	bool	true	Transient banners for incoming notifications — a card with a countdown bar that follows the focused monitor, freezes on hover and respects do-not-disturb (critical still breaks through). Only when wam-shell's daemon is used
popup_timeout	ms	5000	How long before a popup hides itself, when the notification does not ask for a length of its own. Low urgency drains in half the time; critical stays until dismissed
position	"topRight" / "topCenter"	"topRight"	Where banners appear
popup_width	int (px)	460	Fixed banner width; the whole stack keeps one width as notifications arrive and expire
transient_apps	list of strings	[]	App names (matched case-insensitively) whose notifications are popup-only: shown as banners but excluded from the center's history
history_retention_days	int (days)	1	Days a desktop notification stays in the center's main history before it moves to the archive — hidden from the main list, still browsable through the archive band below the list. 0 archives nothing. Criticals are exempt: they stay active until dismissed
archive_retention_days	int (days)	7	Days a desktop notification is kept at all before it is deleted from the daemon, measured from arrival. 0 keeps the archive forever; keep it larger than history_retention_days
popup_providers	list of strings	[]	Provider names ("github", "youtube", …) whose items may also raise transient banners alongside the center; empty = provider notifications live in the center only
snooze_presets	list of minutes	[15, 30, 45, 60, 120]	Minutes offered by the DND menu's "Snooze notifications" items (right-click the DND button in the center); picking one turns do-not-disturb on for that long, then restores its previous state
snooze_when_sharing	bool	false	Factory default for the DND menu's "While screen sharing" checkbox: notifications stay silenced whenever a screen share or camera is active. The checkbox is remembered once toggled and overrides this default

• The daemon choice is made at startup — restart the shell after changing daemons. Forcing "wam-shell" while another daemon already owns the bus name still leaves notifications with that daemon.
• A notification whose app sent a "default" action — and every provider item, which always opens — carries a small external-link mark beside its timestamp, on both the banner and the center row; hovering it says what a click will do (the action's own label). Dismiss-only rows carry a dim close mark in the same slot instead: no action is attached, so the body click does nothing and the only move is dismissal (swipe or right-click a banner; hover a center row for its Dismiss button).
• A sender's requested timeout always wins over popup_timeout (0 = stays until dismissed); the setting only applies when the sender leaves it unspecified.
• Notifications carrying the spec "transient" hint are always excluded from the center, regardless of transient_apps.
• Deletion past archive_retention_days is enforced by an hourly sweep plus a filter on the lists, so a row can linger up to an hour past the cutoff before it disappears.
• Both retention keys apply to desktop notifications only — provider items (GitHub & co.) keep their own caches and are unaffected.
• Provider banners respect do-not-disturb, and the first sync after startup is a silent baseline — no banners for items that were already there.
• DND snooze — right-click the center's DND button: snooze presets (snooze_presets), a "While screen sharing" checkbox and a "Cancel" row. A snooze turns do-not-disturb on and restores its previous state when it ends; any manual DND toggle cancels it (turning DND off during a share hold also unticks the checkbox, so it cannot silently re-engage on the next capture). Criticals still break through, banners already on screen stay, and the center keeps collecting history. A running snooze does not survive a shell restart — DND simply stays on.
• The center's clear-all drains a large local list over a second or two without freezing; the button shows a spinner (and a "Clearing N of M…" tooltip) while it works, and the list updates once at the end.