Notifications & Sound

Overview

When you have multiple agents running in parallel, keeping track of what needs your attention is the core challenge. Canopy's notification system is built around three delivery layers: in-app toasts for immediate visual feedback, a notification center for scrollable history, and OS-native alerts that reach you even when Canopy is in the background. An independent sound system provides audio cues for agent events, git operations, and worktree actions.

Most notification features are off by default. The system ships with a minimal soundscape so you can enable the specific events you care about without being overwhelmed from the start.

In-App Toasts

Toasts appear in the top-right corner of the app window, just below the toolbar. Each toast is glass-styled with a colored left border that indicates its type: success (green), error (red), info (blue), or warning (amber).

A maximum of 3 toasts are visible at once. When a fourth notification arrives, the oldest toast is dismissed and its entry in the notification center is re-flagged as unread, so you won't miss it.

Toasts auto-dismiss after 3 seconds by default. Hovering over a toast pauses the dismiss timer, giving you time to read longer messages or click action buttons. Error toasts use assertive screen reader announcements; other types use polite announcements.

Notification Center

Click the bell icon in the toolbar to open the notification center. An unread count badge appears on the bell when there are notifications you haven't seen.

The dropdown lists notifications in reverse chronological order. Related notifications from the same agent run are grouped into threads, so a burst of events collapses into a single expandable entry. Two filter tabs let you switch between All and Unread views.

Actions available in the notification center:

• Mark all read (checkmark icon) clears the unread badge
• Clear all (trash icon) removes all entries and closes the panel
• Configure opens Settings > Notifications directly
• Individual entries can be dismissed with the X button on hover

The history buffer holds up to 200 entries. When the buffer is full, the oldest entry is pruned to make room.

OS Notifications

OS-native alerts are delivered through Electron's notification API. These appear as system notification popups, reaching you even when Canopy is minimized or behind other windows. Clicking an OS notification brings Canopy to the foreground and navigates directly to the relevant agent or terminal.

Dock badges and window title indicators are separate from OS notification popups. These always-on indicators show the count of waiting agents across all terminals, regardless of watch state:

Agent Notification Events

Five distinct agent events can trigger notifications. Each is independently configurable in Settings > Notifications.

Completion

Fires when a watched agent finishes its task. This event is off by default (completedEnabled: false), since completion is less urgent than an agent needing your input.

Completion uses a 2-second debounce window. If multiple agents finish within that window, they are coalesced into a single OS notification ("N agents finished their tasks") and a single sound event. This prevents notification storms when several agents wrap up at roughly the same time.

Waiting

Fires when a watched agent pauses and needs your input. This is on by default (waitingEnabled: true), since a waiting agent usually means something needs your attention.

Waiting notifications fire immediately (no debounce), with a 200ms burst window to catch simultaneous events. Two grace periods prevent false alerts:

• Spawn grace period (5 seconds) suppresses sounds from agents that start directly in a waiting state
• Boot grace period (8 seconds) suppresses sounds when the app first launches, preventing replay noise from agents that were already waiting

Waiting Escalation

Re-notifies you when a docked agent has been waiting for longer than a configurable delay. This is useful for agents running in the background dock that you might not be actively monitoring.

Escalation is off by default (waitingEscalationEnabled: false). When enabled, the delay can be set to 1, 3 (default), 5, or 10 minutes. If multiple docked agents are still waiting when the escalation fires, they are grouped into a single notification.

Working Pulse

A periodic audio cue that plays while a watched agent (or a docked agent with escalation enabled) is actively working. This gives you an ambient sense of progress without needing to check the UI.

Working pulse is off by default (workingPulseEnabled: false). When enabled, it waits 10 seconds before the first pulse, then plays at random 8 to 10-second intervals. The pulse uses a separate audio channel that bypasses sound dampening. It stops automatically when the agent leaves its working state or when you focus the terminal.

All-Clear

A celebratory sound that plays when all concurrently active agents have finished. This is automatic with no setting to toggle. It only fires when two or more agents were running at the same time, so a single agent completing plays its standard completion sound instead.

All-clear uses a 500ms debounce to confirm that all agents have truly finished (a new agent might start in that window). The sound always plays at full volume regardless of the current dampening state.

Sound System

Canopy includes 14 built-in sounds that play in response to agent events and UI actions. Sounds are routed through the Web Audio API when a window is available, with a fallback to OS-level audio playback when no renderer is active.

Available Sounds

Some sounds ship with multiple variants (.v1, .v2, etc.) that are selected in round-robin order with no immediate repeats. The git and worktree sounds, for example, have three-variant sets.

Sound Dampening

When multiple events fire in quick succession, the sound system applies exponential volume decay to prevent acoustic overload. Each consecutive sound plays at 70% of the previous volume, down to a floor of 10%. Dampening resets after 2 seconds of silence.

A maximum of 3 audio voices can play concurrently. When the pool is full, lower-priority sounds are dropped. The priority order (highest to lowest) is: error, waiting, chime/complete, ping, pulse.

Chord detection handles the specific case of multiple agents completing within 2 seconds. Rather than playing overlapping completion sounds at decaying volumes, the system plays a single unified chord sound at full volume.

The Preview button in notification settings always plays sounds at full volume, bypassing all dampening.

UI Feedback Sounds

A separate category of sounds for non-agent events. These are controlled by their own toggle (uiFeedbackSoundEnabled, off by default) and cover git operations, worktree lifecycle, agent spawning, and context injection.

UI feedback sounds are independent from agent notification sounds. You can have agent sounds enabled and UI sounds disabled, or vice versa.

Settings Reference

Global notification and sound settings live in Settings > Notifications. Per-project overrides are configured separately in Project Settings (see below).

Sound file fields accept any of the built-in sound names. You can preview each option directly in the settings panel before committing to a choice.

Per-Project Overrides

Different projects can have different notification preferences. Open Project Settings (from the project context menu or settings icon) and switch to the Notifications tab to configure overrides.

Each setting in the Notifications tab has a checkbox header. When the checkbox is unchecked, the field displays "(using global default)" and the project inherits your global value. Checking the box activates a per-project control, letting you set a different value for that specific project.

The following settings can be overridden per-project:

• Completed, waiting, and escalation toggles
• Escalation delay
• Sound toggle and per-event sound file selectors (completed, waiting, escalation)

Some override fields are linked. Clearing the waiting override also resets escalation and escalation delay back to their global defaults. Similarly, clearing the sound toggle override resets all three sound file selectors.

Four settings are global-only and cannot be overridden per-project: the master toggle (enabled), working pulse (workingPulseEnabled), working pulse sound (workingPulseSoundFile), and UI feedback sounds (uiFeedbackSoundEnabled). These apply uniformly across all projects.