Preface¶
When developing or running agents in DSH (DeepSeek Harness), sessions can last a long time, and the user’s attention is often elsewhere, on other browser tabs or applications. Without an effective notification mechanism, task completion, approval requests, or error messages may be missed.
The dsh-hybrid-notify plugin monitors window visibility and automatically switches among in-page Toasts, PWA system notifications, and browser notifications based on whether the user is currently in the browser foreground. It also uses the Web Audio API to synthesize sounds, ensuring that critical events are captured accurately.
Core Features¶
This plugin mainly solves the problem of message reach when running in the background. Its core capabilities include:
- Automatic three-channel selection: intelligently dispatches notifications based on window visibility.
- In-page Toast: when the window is in the foreground and visible.
- PWA system notification: when the window is in the background and the PWA channel is available.
- Browser notification: fallback when the window is in the background and no Service Worker is registered.
- Synthesized sounds: uses the Web Audio API (oscillator + envelope shaping) to synthesize tones in real time, without loading any audio files. Sound effects are divided into success, error, warning, and information levels.
- Event-level and channel-level switches: allows controlling individual events such as task completion, subagent completion, and approval requests, and also independently enables/disables the three notification channels.
- Persistence and security: configuration is persistently stored, survives HMR (hot module replacement/hot reload) without losing state, and complies with browser autoplay policy requirements.
Installation and Activation¶
Install the plugin via the DSH CLI:
dsh plugin --profile web add dsh-hybrid-notify
Or install from GitHub source:
dsh plugin --profile web add github:john-walks-slow/dsh-hybrid-notify
After installation, the plugin is automatically integrated into the DSH Web UI.
Configuration¶
Open Settings → Notifications in the DSH Web UI to configure it. All settings are persisted in localStorage under the key dsh.notify.config.
Event Switches¶
The plugin supports independent control of the following events:
| Event Type | Default State | Description |
|---|---|---|
| Task completion | On | A conversation turn has ended (running → idle) |
| Subagent completion | Off | A subagent session has completed |
| Approval request | On | Agent requests approval for an operation |
| User question | On | Agent asks you a question |
| Plan review request | On | Plan mode is waiting for review |
| Agent error | On | Agent encounters an error |
| Background task completion | Off | A background bash task has finished |
Note: Sessions currently being viewed in the foreground will not trigger notifications.
Sound Settings¶
The sound feature includes a master switch, volume slider, foreground playback switch, and a preview button.
Notes¶
- Notification permissions: PWA and browser notification channels require browser notification permission. Permission is requested automatically when the first background event arrives (only when the state is
default); each channel also has a manual authorization button on the settings page. The in-page Toast channel requires no permissions. - PWA / Service Worker: The Service Worker for the PWA channel is hosted by the plugin at
/plugins/dsh-hybrid-notify/sw.js. Environments that do not support it will fall back automatically. - Sound policy: Due to browser autoplay policy restrictions, the AudioContext is unlocked after the user’s first click or keypress interaction. There is no sound before the first interaction.
- Zero network access: The plugin makes no external requests, does not report anything, and all notification content comes from local DSH session snapshots.
- Compatibility: Requires modern browsers that support the Notification API and Web Audio API. Some mobile browsers do not support
new Notification(), and will silently fall back to in-page Toasts. - Build requirements: Building from source requires Node.js ≥ 18.
Summary¶
dsh-hybrid-notify provides a complete solution for background message reach in DSH. Through intelligent channel switching and synthesized sounds, it reduces the need for users to frequently check their tabs, making it suitable for developers and users who need to remain aware of information during long sessions.