English | 简体中文

dsh-sound

Distinct alert sounds for DeepSeek Harness — a host plugin that plays a different sound for each important event, so you always know what is happening without watching the screen.

Features

• Four scenario sounds — network error, approval request, user question, and turn completion each have a distinct, recognizable tone.
• Zero audio assets — all tones are synthesized at runtime and cached under the system temp directory.
• Zero configuration — install and forget; sane defaults handle throttling and noise control.
• Non-intrusive — the plugin only observes host events and never interferes with agent execution.
• Noise-aware — a 3-second global throttle and an 800 ms per-agent debounce prevent sound spam; subagent completions are silent by default.

Sounds

Moment	Sound	Trigger
Network error	Low double-buzz (220 Hz)	An agent run fails (network / API / runtime error)
Approval required	Single mid tone (587 Hz)	A tool call is waiting for your approval
Question asked	Rising "ding-dong" (880 → 1320 Hz)	The agent asks you a question
Turn completed	Cheerful ascending pair (523 → 784 Hz)	A turn finishes successfully

Requirements

• DeepSeek Harness — any recent release; the plugin is a standard host-side Cordis plugin.
• Audio backend (auto-detected, no setup needed):
  • Windows — PowerShell 5.1+ (winmm MCI)
  • macOS — afplay (built-in)
  • Linux — paplay (PulseAudio), aplay (ALSA), or ffplay, tried in order

Installation

dsh plugin --profile web add "github:yeshimei/dsh-sound"

Replace web with your actual profile name if it differs. Then restart the service to activate the bundle:

dsh --profile web

Usage

Nothing to configure — sounds play automatically:

You hear…	It means…	What to do
Low double-buzz	An agent run failed	Open the session and inspect the error
Single mid tone	A tool call awaits your approval	Approve or reject it
Rising "ding-dong"	The agent asks you a question	Answer it
Ascending pair	A turn finished	Read the reply when you are ready

Approval sounds always play — an approval always needs a human — even when the requesting agent is a subagent. All other subagent events stay silent by default.

How it works

The plugin subscribes to host events only:

Sound	Event
Error	agent/error
Approval	session/event — approval/asked
Question	session/event — tool/call with name ask_user_question
Done	session/event — turn/end with reason completed

All tones are synthesized in lib/sounds.js as 16-bit PCM WAV files (44.1 kHz mono) and played through the platform's native audio tool - PowerShell/winmm on Windows, fplay on macOS, paplay/play/fplay on Linux - in a detached child process, keeping the host fully isolated from playback failures.

Repository layout

lib/index.js      Plugin entry point — event wiring, throttle & debounce
lib/sounds.js     Runtime WAV synthesis for the four tones
lib/play.js       Cross-platform playback dispatcher (PowerShell / afplay / paplay / aplay / ffplay)
play.ps1          MCI playback script (ASCII + UTF-8 BOM for Windows PowerShell 5.1)
cordis.patch.yml  Bundle patch layer (declared via dsh.bundle.patch)
tests/            Test suite (Node built-in test runner, npm test)

Development

Run the test suite with the Node built-in test runner (no dependencies):

sh npm test

Uninstall

dsh plugin --profile web remove dsh-sound

Restart the DSH service afterwards.

Privacy

Everything runs locally. No data leaves your machine.

License

MIT