Introduction¶

When running Agents in DeepSeek Harness (DSH), users often stare at other windows: when will a round end, is there an error, is it waiting for approval or a question? The interface state alone isn’t intuitive enough. Switching back to DSH to check logs is also exhausting. The dsh-notify-chime plugin listens to session events and plays distinct short sounds at a few fixed types of nodes. It can also optionally pop up system notifications, turning “whether I should click back” into an audible and selectable banner feedback. Below is an introduction to the plugin’s positioning, installation, setup, and points to note during use.

What is it¶

dsh-notify-chime is a community-maintained DSH workflow plugin, maintained by dixieWithHeart. The current package version is 1.8.0 (referencing package.json), license MIT, and requires Node.js >= 20. The plugin provides cordis.patch.yml with the package, which writes to the host configuration automatically after installation; host-side logic is in lib/host.js, and the settings page injects the DSH settings UI via client.js.

In short: it makes sounds in scenarios like round completion / interruption / error / Agent question, and on Windows and other platforms, Toast is optional; eight types of events can be individually toggled and have different tones, supporting custom audio files.

Ecosystem-wise, DSH advocates “everything is a plugin”; the SkillHub directory page and GitHub repository are community sources, with no official app store affiliation with DeepSeek / Hypersphere. It is advisable to view the source code and license yourself before installation; the plugin runs with the current dsh process permissions.

Core Features: Eight Event Types and Default Tones¶

The plugin distinguishes scenarios by kind, with built-in default tones having consistent semantics: completion tends to be upward, interruption tends to be downward, error is low frequency, and question is high-pitched and urgent.

Since 1.5.0, plan review is no longer mixed with “question”. Goal blocked only sounds on the transition from non-blocked to blocked; background task failure is debounced by a 3-second session window, so multiple tasks failing at the same time only sounds once.

Silent scenarios (clearly documented): app exit, session fork, being blocked, and subagent sessions that are filtered by default. The listener monitors the session log append stream; cold-starting to open historical sessions will not trigger sounds.

Installation and Activation¶

The official installation command is as follows (as per the original documentation, do not manually concatenate github:owner/repo):

dsh plugin add dsh-notify-chime

After installation, refresh the page and adjust in Settings → Chimes. Settings take effect immediately upon saving; no need to restart DSH.

Settings Page Structure¶

There are three groups of configuration; when the global switch is off, no sound or notification is played, but events are still recorded, and the settings page remains accessible.

User-modified items are written to ~/.dsh/dsh-notify-chime.json; items not changed in the interface still follow the initial values from cordis.patch.yml.

Interface language: The English and Chinese text in the settings page switches with DSH Settings → General → Language, without requiring a restart. System notification titles and bodies are generated by the host; the documentation currently states they are fixed in Chinese.

Tones and Custom Sounds¶

There are six built-in sound sets that only change the listening experience, not the trigger rules: default, soft, chime, retro, digital, wood (specific tones are in the README table). The selection at the top is the global default; a specific event type can be specified individually by clicking “Follow Global ▾” in the row.

After a tone is selected as “Custom” in a row, an “Upload” button appears:

• Supports WAV / MP3 / M4A / AAC, single file ≤ 5 MB; WAV uses SoundPlayer, others use WPF MediaPlayer
• Stored in ~/.dsh/dsh-notify-chime-sounds/<kind>.wav; uninstalling the plugin does not delete the files

The built-in WAVs under assets/ are synthesized by tools/make_sounds.py included in the package, distributed under MIT, with no third-party samples.

Initial Configuration and Advanced Options¶

The config in cordis.patch.yml is only the initial value; after saving in the interface, the JSON settings file takes precedence. Typical snippet:

- id: dsh-notify-chime
  config:
    enabled: true
    soundset: default
    minIntervalMs: 700
    includeSubagents: false
    kinds:
      finished: true
      interrupted: true
      error: true
      question: true
      approval: true
      plan-review: true
      goal-blocked: true
      job-failed: true
    toast: { enabled: true, kinds: [question], includeSession: true }

Common field meanings (default values refer to the README table):

• enabled: Initial global switch value; when false, the plugin still loads and the settings page is available
• soundset: Global tone, including custom
• minIntervalMs: Minimum interval for the same event type (default 700), prevents continuous ringing
• includeSubagents: Whether to make sounds for subagent sessions (default false)
• quietCurrent: No sound when the session currently being viewed finishes (only affects completion types)
• kinds.<kind>: Whether that type plays sound
• toast.*: Whether to pop system notifications, for which kinds, title prefix, whether to include session name; on Windows, toast.appId defaults to com.deepseek.dsh, which must be a registered AppUserModelID

You can also hardcode paths or mute specific types in the patch, for example:

- id: dsh-notify-chime
  config:
    sounds:
      finished: C:/Windows/Media/Windows Print complete.wav
      error: false

Debugging trigger records: specify a path for traceFile, and a JSON line will be appended for every trigger; if not configured by default, no file is written.

System Notifications and Platform Behavior¶

• Windows: WinRT Toast
• macOS: osascript
• Linux: notify-send

When appId is not registered in the system, notifications may only enter the notification center without popping a banner. The documentation provides commands like tools/check-notifications.py and tools/try.mjs toast for troubleshooting on Windows, and suggests checking system notification switches and Do Not Disturb mode.

Typical Usage: Local Testing and Smoke Tests¶

You can verify sound effects and notifications without relying on a real session:

node tools/try.mjs all        # Test four sound effects
node tools/try.mjs toast      # Test popping notifications
node tools/smoke-test.mjs     # Contract smoke test, in a temp directory, doesn't touch real settings, doesn't make sound
node tools/smoke-test.mjs --verbose

Regenerate built-in WAVs (optional):

python tools/make_sounds.py          # Regenerate all
python tools/make_sounds.py chime    # Regenerate a single set

Use Cases and Limitations¶

Who is this for: DSH users who let Agents run in the background for long periods and need to distinguish “normal end / interrupted / error / waiting for you to answer or approve” via sound; users who want system notifications paired with question events to reduce window switching.

Implementation Limitations (key points from the original README):

• Each reminder plays via an independent subprocess, not blocking the Host; PowerShell cold start is about 200 ms, perceived latency is about 0.3 s
• No volume adjustment inside the plugin, follows the system default output device; virtual sound cards may cause unclear audio
• Custom formats do not support WMA, FLAC
• Pause: Global toggle in the settings page; Uninstall: dsh plugin remove dsh-notify-chime, settings file can be retained or deleted

Conclusion¶

dsh-notify-chime maps several key nodes in the DSH round lifecycle into configurable alert sounds and optional system notifications, using eight kinds, six tone sets, and debounce rules to reduce false positives and continuous ringing. To install or view version notes, see the SkillHub directory and GitHub: dixieWithHeart/dsh-notify-chime.