Delivery, Focus and Muting
How Daintree decides whether something interrupts you: toast routing and burst collapsing, the attention gates including Do Not Disturb and Quiet Hours, OS-level focus, per-project muting and silencing, watched terminals and OS notifications, and the banner surfaces.
Toasts
Toasts appear in the top-right of the app window, under the toolbar, glass-styled with a colored left edge for their severity. At most three are visible at once; when a fourth arrives, the oldest toast that is not an error makes way, so an error stays on screen through a burst of successes.
Auto-dismiss timing sits at the middle of the published range rather than the top of it: errors and warnings 8 seconds, info 6, success 5. A toast carrying an action button is sticky and waits for you. The timer pauses while the pointer is over the toast, while keyboard focus or its options menu is in it, and while the window is in the background. Error toasts announce assertively to screen readers; the rest announce politely.
The persistent inbox lets you recover recorded notifications after their toasts disappear. Rich toast messages supply a plain-text history version on the regular notification path. Transient confirmations are the exception: they have no inbox record, as described below.
An in-app toast about a watched agent (finished, waiting, exited) is held back while you are looking at that panel, because the panel already shows it. If you move away within half a second, the toast appears after all.
Toasts fired into a window you are not looking at
A high-priority toast only fires when the Daintree window is focused. Blurred, it goes to the inbox instead, marked unseen.
That is a deliberate correction of an earlier behavior. A toast rendered into a background window would run its dismiss timer, disappear unwatched, and mark its inbox entry as seen, quietly removing it from the unread count and from the re-entry summary. The event you most needed to know about was the one most likely to be swallowed. Now a blurred window routes everything to the inbox unseen, so it is waiting when you come back. A toast pushed off the screen by the three-toast cap goes back to unread in the inbox, the bell blips, and a +N more pill under the stack opens the inbox. While the inbox is already open the pill and the blip are skipped: signalling an arrival you can watch land would be a contradiction.
The same rule governs the grid bar: while notifications are disabled or a quiet gate is active, a grid-bar entry is not shown and is written to history unseen, so turning notifications back on does not present you with a pile of already-read events you never saw.
Collapsing bursts
Four mechanisms keep a noisy producer from taking over the screen, and they solve different problems:
- Coalescing collapses a burst into a single updating toast over a short window, roughly two seconds, with a count in the title. Used where several events arriving together really are one event.
- Rate limiting catches slow drips that sit outside the coalesce window. Each source gets a bucket of three toasts refilling at one per ten seconds; overflow drops the toast entirely and aggregates into a single in-place summary row in the inbox. It only engages when a toast would actually have fired, so a blurred or muted window does not accumulate summary rows alongside the normal entries they are meant to replace.
- Superseding retires a stale entry when its resolution arrives. "Disconnected" is archived automatically when "reconnected" lands, so the inbox does not accumulate rows describing states that are no longer true.
- Transient notifications are toast-only, with no inbox entry at all. Reserved for one-shot confirmations whose result is already visible elsewhere, like the Marked 3 as read confirmation and its Undo.
A confirmation toast that carries Undo skips the rate limit and the quiet gates below. You just made the change, and an Undo held back until quiet hours end would expire unseen.
Attention Gates
Three things can hold a notification back, and they stack. Because working out the combined effect in your head is exactly the kind of thing software should do for you, the inbox states the answer directly.
The "what will fire" summary
Whenever something is holding notifications back, a strip under the inbox header says so. Its first line names the cause: Muted until 10:56 PM, Quiet hours, OS Do Not Disturb is active, or Some notifications are off when the only thing at work is a silence you set. The lines under it fill in the rest:
- Any other cause active at the same time, such as Quiet hours continue until 8:00 AM under a session mute, so Resume never reads as the end of a quiet it does not end.
- While a mute or OS Do Not Disturb is in effect, what still breaks through: Will interrupt you: Waiting, System, or Nothing will interrupt you right now. Under OS Do Not Disturb alone this becomes Daintree's own alerts still show, because the OS silences its banners, not the app's.
- The kinds you have switched off, such as Off: Completed, so a kind missing from the line above is never ambiguous between "held for now" and "turned off". Only Completed and Waiting can appear here: switching off the working pulse or the UI sounds reads as sound off rather than kind off. With no mute or OS Do Not Disturb in effect, Completed is left out, because it ships off.
- Project silences: This project is muted, This project: Waiting off, or Silenced in api and web for other projects with rows in the inbox.
A session mute carries a Resume button; quiet hours or a silence carry Manage, which opens notification settings. With nothing held back, the strip is not shown.
The summary is computed from the gate state directly, with no round trip to the main process, so it is correct the instant the inbox opens. Every kind resolves to one of six states: will interrupt, quiet-gated (would interrupt, but a mute is holding it), kind off, sound off, inbox only for the passive kinds, or disabled when the master toggle is off.
Do Not Disturb
Pauses delivery for the current session. Open the inbox and click Pause notifications (the moon icon). The menu offers For 1 hour and Until {time}, labelled with the next 8:00 in your clock format, plus Schedule quiet hours…, which opens notification settings.
While DND is on, the toolbar bell switches to a struck-through icon, its tooltip says until when, and the inbox strip leads with Muted until {time} and a Resume button. The session mute is not persisted, so quitting clears it.
Quiet Hours
The scheduled version, under Settings > Notifications > Quiet hours. Turn on Mute on a schedule, then set Hours (a start and an end, in 15-minute steps) and Active days. The default window is 22:00 to 08:00. It can cross midnight; the row then reads 22:00 to 08:00 the next day, and an overnight window counts toward the day it starts. Two details worth knowing:
- Setting start and end to the same time shows "Start and end match, so the schedule does nothing until the times differ" rather than silently doing nothing.
- Every day starts selected. Turning all seven back on is stored the same way as never touching them, so the two ways of saying "every day" cannot disagree, and the last selected day cannot be turned off: to stop the schedule, turn off Mute on a schedule.
During Quiet Hours the bell shows the struck-through icon and the inbox strip leads with Quiet hours and a Manage button. When a session mute and a scheduled window overlap, the strip names both, and an empty inbox shows the resume time that actually unblocks you last.
Both gates pause delivery, nothing else. The inbox keeps recording. Urgent items break through, and agents waiting for input page through the OS layer regardless, because a blocked agent is blocking your work whether or not it is a convenient time.
OS-level Do Not Disturb
Daintree also reads your operating system's own Do Not Disturb or Focus state and surfaces it, so a silent app is never a mystery. When it is on, the inbox strip shows "OS Do Not Disturb is active" and the bell's tooltip says the same.
It is a display signal and also suppresses informational sound and flash cues, including the working pulse and all-clear. In-app toasts are not suppressed by it: the OS already silences its own banners, and double-gating would hide signals inside the app window that the OS was never hiding.
Detection is macOS-only. The initial state is probed from the system's Focus assertions, and live transitions come from the system's own DND notifications. On Windows and Linux the state stays unknown (Windows Focus Assist exposes no subscription to Electron and cross-desktop Linux detection has no reliable standard), and unknown means nothing extra is shown rather than a guess.
Muting & Silencing
Where the gates pause everything for a while, muting and silencing are narrow and persistent. Both sit on a toast's kebab and on an inbox entry's kebab:
- Silence {event kind} from this project turns off one event kind for one project and leaves the rest alone. The kind names itself in the menu item, so the item reads "Silence completed notifications from this project" rather than something generic. It takes effect for completed and waiting notifications, the kinds with a per-project switch. Silence UI feedback sounds turns those cues off for every project, because they have no per-project setting.
- Mute project notifications switches off that project's completion and waiting alerts together.
Once both are off, a struck-through bell appears on the project's worktree cards in the sidebar and on its row in the project switcher, so a muted project is visible without opening its settings, and the inbox strip says This project is muted. These live in the project's settings, survive a restart, and stay in effect after a DND or Quiet Hours window ends. To turn them back on, reset the rows in the project's Notifications settings.
Project muting and Do Not Disturb are independent. Muting is persisted configuration for one project; DND is a temporary global pause. Ending DND does not un-mute a project, and muting a project pauses nothing else.
OS Notifications
OS-native alerts go through Electron's notification API, appear as system popups, and reach you when Daintree is minimized or behind another window. Clicking one brings Daintree forward and jumps to the relevant agent or terminal.
In a window on a remote host, native notifications are titled with the host's name, studio-01: …, and use this machine's sounds and session mute; project notification rules and project muting belong to the host. Agents waiting on a host no window is showing reach you only if Notify me about this host is on for it; see Notifications.
Watching a terminal
Completion and waiting alerts fire only for watched terminals. A watched terminal raises an in-app toast when its agent finishes, exits or starts waiting, and an OS popup too when Agent completed or Agent waiting for input is on in Settings > Notifications. An agent running unwatched raises neither, even when those settings are on. To watch one, choose Watch in the panel header's menu or Watch terminal on the terminal's right-click menu; the header shows a bell while the watch is on. A watch is one-shot: it fires once, when the agent finishes, exits or starts waiting, and then ends. Watching a terminal whose agent has already finished or is already waiting shows its toast straight away instead.
Two signals do not need a watch:
- Waiting escalation re-notifies about docked agents still waiting after a delay, when you have turned it on. See Waiting escalation.
- With Canopy turned on, an agent Canopy reads as asking for approval or asking a question pages you through the same waiting banner and sound, unless Canopy is already open in front of you.
A waiting popup is held back while you are present and already looking at that agent's worktree in a focused window, and it closes itself once the agent stops waiting.
Waiting reasons
"An agent is waiting" is not a useful signal when four of them are. Daintree classifies why an agent stopped and carries that into the notification body, so you can triage from the banner without switching apps:
| Reason | Notification body | What it means |
|---|---|---|
approval | "… is waiting for approval" | A one-keystroke unblock. Highest triage priority. |
error | "… is blocked by an error" | Hard-blocked and burning wall-clock silently. |
question | "… asked a question" | Needs a considered answer. |
prompt | "… is waiting for input" | The classifier's fallback, with no positive evidence either way. |
The ordering above is the triage order the app uses everywhere the reason appears, ranked by leverage per second of your attention. prompt never earns a specific label, because it is the absence of evidence rather than a finding; it and an unclassified state both present as the generic "waiting for input". When several agents are grouped into one notification, the specific wording is used only if every agent in the group shares the same reason: a mixed group falls back to the generic phrasing rather than overclaiming for any member. The same vocabulary drives the terminal header chip, the waiting popover, Fleet badges and screen-reader announcements, so one agent reads as one signal everywhere. See Agent States.
Dock badges and window title counts are separate from OS popups. They are always on and count agents watched or not: while a window is in the background, its count is the agents that started waiting since you left it and are still waiting. The agent count clears when the window takes focus again. Each pane with a Decisions question still waiting for you, unseen and uncleared, also counts once, and focus doesn't clear it.
The dock icon shows a badge count, the total across your windows, and each window's title gains the same count in front of the project name: (2) atlas-ledger. System notification popups appear in the top-right of the screen.
The window title gains the count in front of the project name, (2) atlas-ledger (or (2) Daintree with no project open), and the taskbar label shows it. Notification popups go through the system tray.
The window title gains the count in front of the project name, (2) atlas-ledger (or (2) Daintree with no project open). Popups go through the desktop environment's notification daemon.
Banners
Banners carry state rather than events, and Daintree splits them by whether you can act on them.
Global banners are advisory
A single slot at the top of the window holds app-wide conditions. Exactly one renders at a time, chosen by a fixed priority order, highest first:
- Host connection: in a window on a remote host, the link to the host is down or the host runs a different build. Never shown in a window running on this machine.
- Host crash: the backend is unusable right now.
- Drive lease: another machine is driving this project, so its terminals take no input here until you take it back.
- Watchdog disabled: the deadlock detector is gone, so the protection layer is down.
- Terminal host memory stall: a terminal host's memory pause is not recovering, so terminal output is slowed now.
- Safe mode: panels were not restored after a crash loop.
- Restore confirmation: the informational "session recovered" banner.
- Missing prerequisite: a required tool such as Git or Node is not installed.
- Plugins need a window reload: plugin registrations can't be replaced until the project window reloads.
- Cloud sync: the project sits in a synced folder.
- Rosetta: an x64 build being translated on Apple Silicon.
The ordering is by urgency and blast radius rather than by category. In a remote window nothing below the host link is reachable while it is down, so that comes first. A live host failure outranks a downed monitor; the watchdog outranks safe mode because it protects against the next crash while safe mode is a consequence of the last one; a stalled terminal host is a live problem, so it outranks the two banners about the previous session; and Rosetta sits last because nothing in the app can change it. Restore confirmation stays high despite being purely informational, because its auto-dismiss timer only runs while it is mounted. An expired forge token is not a global banner at all: it breaks one project's forge data, so it shows as a callout on the forge pill instead.
Suppressed banners are unmounted rather than hidden, so a banner's timers only run while you can actually see it. On Windows, the native caption strip is told which banner color sits beneath it, and the swap is coalesced so a change from warning to error does not flash back through the canvas in between.
Pane-local banners are actionable
An error that belongs to one panel renders inside that panel, next to the thing that failed and next to the control that retries it. A terminal that could not reattach, a spawn that failed, a worktree move that did not complete, a file browser, file viewer, diff viewer or dev preview that hit an error: each shows its own banner in its own pane.
The split is the point. A global banner tells you something about the application; a pane-local banner tells you something about the thing you are looking at, and gives you the button that fixes it. Neither one is a toast, because neither describes an event that happened at a moment: they describe a state that is still true.
The grid bar
The grid bar is a single inline slot above the panel grid for notifications that should stay put rather than float: processes that outlived their terminals (with View processes), terminal output that has stalled, or a forge integration you could turn on. Contention for the slot resolves by priority and severity, with ties going to the oldest, and a newcomer cannot preempt the current occupant within its first 5 seconds: otherwise a burst of producers could strobe the bar and make it unreadable. Every grid-bar notification carries a Dismiss control after any action buttons of its own, so a stale one is never stuck on screen.