Introduction¶

When running long sessions with the DSH desktop app, the window is often covered by other applications. When a turn ends, an error occurs, or approval or answers are required, if there are no system-level alerts, you have to switch back to DSH repeatedly to check the status. Browser notifications offer a limited experience on Windows, and the variety of system-built Toast notification sounds is sparse, making it difficult to distinguish between “Finished,” “Error,” “Waiting on you,” and “Still waiting.”

Below is an introduction to the community plugin dsh-notify-desktop (maintained by paleech0). When configured with the DSH desktop app on Windows, it pops up native Toasts at appropriate moments and plays selectable notification sounds based on the scenario. Clicking the notification brings the DSH window to the foreground. The plugin is categorized as a client and can be found in the SkillHub directory. For source code and instructions, see GitHub (npm package name dsh-notify-desktop, version 0.1.1 in current materials, license MIT).

What is this¶

dsh-notify-desktop is aimed at the DSH desktop application (profile desktop) and does not modify the Harness core. On one side, it registers session projections and local routing on the host; on the other, it decides whether to notify based on session state in the renderer process. It triggers a Toast (deduplicated within approximately 3 seconds) only when the window does not have focus during events such as session completion, failure, abortion, blocking, reaching max-tokens, or occurrences of approval requests, questions, plan reviews, or long wait times. It does not pop up when the window is in the foreground. Clicking the Toast focuses DSH via dsh://open but does not automatically jump to a specific session.

Runtime requirements (from README): Windows, DSH desktop, runtime 0.2.x. The declared compatibility range is >=0.2.0-rc.2 <0.3.0-0. Optional: ffmpeg on the system PATH, used only for transcoding custom audio that is not in .wav format.

Core Features¶

Notification Timing¶

Capabilities listed in the materials include:

• End of turn: completed, error, aborted, blocked, max-tokens, etc. These can be toggled individually by reason in the settings.
• Requires your intervention: Approval requests, questions, plan reviews, etc. Questions within tool calls go through the session projection; service-level questions (such as plan reviews) are listened to by the host via user-questions/request and then passed to the client, avoiding missed notifications or duplicate Toasts.
• Waiting reminders: Long waits can be configured with a single “nudge” after a specific number of minutes, complete with a test button.

Quiet Mode and Deduplication¶

Notifications do not pop up when the DSH window has focus. The same event is notified only once within approximately 3 seconds. When the master switch “Enable notifications” is turned off, all other items become ineffective.

Scenario-based Sounds¶

There are four categories: finished, error, waiting on you, and still waiting. Each group allows you to select a sound source and preview it individually in the settings:

1. Windows sounds — Approximately twenty items (Toast related events and media library entries, such as chimes, ding, Windows Error, etc.).
2. Author sounds — Four .wav files bundled in the plugin’s sounds/ directory. Dropping files into this directory will make them appear in the list.
3. Custom sounds — Imported via “Add sound…”. Files are copied to %LOCALAPPDATA%\dsh-notify\custom.

File sounds play for a maximum of 8 seconds. Turning off the master sound switch or when the window regains focus causes any currently playing sound to stop immediately. Non-.wav formats are transcoded via ffmpeg and enter the transcoding cache (viewable and clearable on the settings page). If ffmpeg is missing, wav files and the two libraries mentioned above can still be used, and diagnostics will show media.ffmpeg: null.

Supported import formats (README): .wav, .mp3, .m4a, .aac, .wma, .flac, .ogg, .opus.

Settings Entry¶

After installation and a restart of the desktop app, access it via Settings → Notifications (Ctrl+, when the window is focused). Preferences are written to the renderer’s localStorage and take effect immediately. The master switch, master sound switch, sound selection for each group, custom sound management, transcoding cache, switches for various end reasons, switches for various interaction types, waiting reminder minutes, etc., are all centralized in this settings area (see README settings table).

Installation and Enablement¶

The plugin runs with the current DSH process privileges. Before installing, it is recommended to read the repository source code and the MIT license to ensure it complies with your environment policies.

Install from npm¶

Replace <DSH desktop install> with the installation directory of your local DSH desktop version, and run the following in PowerShell:

& "<DSH desktop install>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-notify-desktop

Restart the DSH desktop app after execution, then open Settings → Notifications to configure as needed.

Local Directory Link (Optional)¶

If using a local checkout directory instead of the npm package, the README requires placing the repository in a persistent path and registering it via the desktop CLI (replace the path with your directory):

& "<DSH desktop install>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "link:<path-to-this-repo>"

Restarting the app and entering the notification settings are also required. The main task requirements do not include writing git clone steps; see the GitHub README for complete instructions.

Version Mismatch¶

The loader checks the DSH version according to peerDependencies and skips the plugin if unsatisfied. If you need to force permission outside the declared range, the README provides an example (at your own risk):

dsh.cmd plugin --profile desktop allow-version dsh-notify-desktop@0.1.1 --dsh-version <your-version> --accept-risk

Typical Usage and Troubleshooting¶

Daily Use¶

1. Install and restart as described in the previous section.
2. Open Settings → Notifications, enable Enable notifications, and turn on the various “When to notify” and Waiting on you items as needed.
3. Select sound sources for the four sound groups and click preview. Use Add sound… if custom audio is needed.
4. Put DSH in the background, trigger a session end or a question; you should see a Toast. Clicking it will bring the main window to the foreground.

Diagnostics¶

Windows Toasts do not necessarily appear in the Action Center. The README suggests using the local debug route to view projection status, the last ~40 client decision records, and ffmpeg / player status:

Invoke-WebRequest http://127.0.0.1:19387/dsh-notify/debug

Applicable Scenarios and Notes¶

The plugin exposes several same-origin routes on the host side (such as POST /dsh-notify/toast, POST /dsh-notify/focus, etc.) to allow the client half to complete Toasts, focusing, and muting. See the README section “How it works” for details; general users only need the settings page.

Conclusion¶

dsh-notify-desktop connects the moments in the DSH desktop app where you “need to be called back” to native Windows notifications and configurable sound effects, while remaining quiet when you are already in front of the window. For entry information and categorization, you can open the SkillHub plugin page. Installation commands, sound behavior, compatibility ranges, and troubleshooting are subject to the GitHub repository README (including Chinese documentation README.zh.md).