Notifications & Sound Packs

Workbench has a customisable notification system built around the moments when you actually want the app to grab your attention — when an agent needs your input, when a task finishes, when something goes wrong. You can pick a different sound for each kind of event, or swap the entire sound palette out for an OpenPeon community sound pack.

Notification Events

Five distinct events can trigger a sound:

Event	Setting key	Fires when…
Input required	notification_sound_ask	The agent is waiting on you (e.g. an AskUserQuestion or plan-mode approval).
Plan acknowledged	notification_sound_plan	A plan you submitted has been accepted by the agent.
Task complete	notification_sound_finished	The agent has finished its turn.
Task error	notification_sound_error	The agent run failed.
Session start	notification_sound_session_start	A new agent session has been kicked off.

Each event has its own dropdown — you can mix and match freely, or set them all to the same sound.

Where to Configure

Open Settings > Notifications. You’ll find:

• A sound source toggle (system sounds vs. OpenPeon sound pack)
• A volume slider (0–100%)
• A mute switch (kills all notification audio without losing your selections)
• One dropdown per event listed above
• An OpenPeon sound pack browser when sound source is set to OpenPeon

Per-Event Sound Resolution

When Workbench decides what sound to play for an event, it walks a small fallback chain:

1. The per-event setting (e.g. notification_sound_finished)
2. The global notification sound, if set
3. The legacy audio_notifications toggle, if it’s set to false (silences notifications)
4. The built-in Default sound

This means an unconfigured event always falls back to something sensible — you don’t have to set every dropdown for the system to work.

OpenPeon Sound Packs

OpenPeon is a community sound-pack registry. Each pack ships a set of category-tagged sound files that map onto Workbench’s notification events (input.required, task.acknowledge, task.complete, task.error, session.start).

Switching the sound source in Settings to “OpenPeon” reveals a pack browser that lets you:

• Search the public registry by name, language, or category
• Install a pack (Workbench downloads a tarball of the pack’s source ref from GitHub and extracts it locally)
• Update an installed pack by re-downloading its current source ref
• Delete an installed pack
• Switch the active pack from the list of installed ones

The relevant settings keys (for the curious) are cesp_active_pack, cesp_volume, and cesp_muted.

Recommended Packs

We maintain two community packs that pair well with Workbench’s defaults — both are listed in the OpenPeon registry and discoverable in the in-app browser:

• Alan Rickman — voice clips from the late great Alan Rickman.
• Elise — a more melodic pack built around Beethoven’s Für Elise.

Context Overflow Warning

A toast notification appears when your session reaches 80% context usage, giving you a heads-up before the context window fills. If a send fails because the context overflowed, Workbench automatically triggers compaction and retries the turn — no manual intervention needed unless compaction itself fails, in which case the error banner offers a Compact & Retry button and a link to switch to a larger-context model.

Divergent Branch Notification

When the local branch and its remote tracking branch have diverged (both have commits the other lacks), Workbench shows a modal notification explaining the situation. The modal offers three resolution options:

• Merge — git merge the remote into local
• Rebase — git rebase local commits on top of the remote
• Fast-forward — only available when the history is linear

This prevents you from pushing a force-update or silently losing remote changes without realising the branches diverged.

Join Notifications

When a remote user connects to your workspaces, a modal appears showing the user’s name and which workspaces they joined. Multiple joins are queued — dismissing one reveals the next. A configurable sound plays when the join fires, and a native OS banner appears if Workbench is backgrounded so you don’t miss it.

Toast Position and Limits

Toast notifications render in the upper-right corner of the window. At most three toasts are visible at once; when more are pending, an overflow pill shows the count of hidden toasts. Press Escape to dismiss all visible toasts at once.

Tray and Native Notifications

Notification sound and any optional command run on the Rust side of the app, not in the webview. That matters in practice because macOS suspends webview JavaScript when the window is hidden — running on the Rust side means notifications still fire reliably when Workbench is minimised, hidden behind another app, or backgrounded into the system tray.

Native notifications are integrated with the system tray:

• macOS uses mac-notification-sys for click-to-navigate banners
• Linux uses tauri-plugin-notification
• Windows uses the platform-native notification surface

The tray menu organises workspaces into submenus per repository so the menu stays within screen bounds when many projects are open. Each repository submenu lists its workspaces, and the top-level menu shows repositories in the same order as the sidebar.

The tray icon and sidebar also reflect unattended workspaces, so even with sound muted you’ll see a visual indicator when a workspace needs your attention.

Sound Playback by Platform

Sound playback is platform-specific and uses each OS’s native audio path:

• macOS — plays AIFF files from /System/Library/Sounds via afplay. The sound dropdown enumerates the same directory.
• Linux — plays via canberra-gtk-play (with paplay as fallback) using freedesktop sound names.
• Windows — has two paths depending on which kind of sound is playing:
  • System sounds (the dropdown items resolved from %WINDIR%\Media, typically C:\Windows\Media) play via the PlaySoundW Win32 API. “Default” maps to the system Notification Default alias, which respects whatever you’ve picked in Settings → System → Sound → More sound settings. PlaySoundW plays at the user’s system volume — fine for short beeps, no decoder cost.
  • OpenPeon sound packs decode in-process via rodio (cpal + Symphonia). WAV, MP3, and OGG all work, and the volume slider attenuates per-call playback exactly the way it does on macOS / Linux.

The split is intentional: short system beeps don’t need a decoder pipeline, and rodio is only spun up when a user actually opts into a sound pack.

Custom Notification Command

If you want a notification to fire your own script — pipe to a Slack webhook, blink a Hue bulb, anything — Settings → Notifications has a custom command field. Workbench runs the command when a notification fires, with a small set of environment variables describing the event.

The command runs in your platform’s default shell:

• macOS / Linux — sh -c "<your command>"
• Windows — cmd.exe /S /C "<your command>". If you need bash semantics, just call it explicitly: bash -c "..." (e.g. via Git Bash or WSL).

This is independent of the sound system: you can use it together with sound packs, or instead of them.

---

Original source: utensils.io/claudette