dsh-sound-alerts

@zaykoff/dsh-sound-alerts

A DeepSeek Harness plugin: sound cues for three agent situations. Audio plays on the Host process machine (for the local Web GUI — on your PC), regardless of browser tab focus.

Situation	Trigger	Default sound
Agent task completed (agent running → idle)	api-session/status	sounds/task_done.wav — three light taps bottom-up (dong-ding-ding)
Context overflow: history compaction started (token-pressure automation, recovery after the context-window error, /compact)	session/event, type compaction/start	sounds/cache_overflow.wav — two low muted hits
Agent asked a clarifying question and awaits an answer	session/event, type tool/call (ask_user_question; fallback: the user-questions/request waterfall for approval questions outside the tool)	sounds/question.wav — two short light ticks

The built-in cues are light drum "taps": a short membrane tone with a fast downward pitch drop plus a soft noise hit, each under 1 s, peak volume around -12 dBFS — unobtrusive, no ringing, no sharp fronts (generated by scripts/make_sounds.py). On Windows only .wav paths are played; when the file is unavailable (or the path is not a .wav), a short sequence of quiet fallback taps plays instead ([console]::beep) in the same rhythms. On macOS — afplay, on Linux — paplay, then aplay; there, a missing file stays silent. A cue of one type never repeats faster than minIntervalMs. Subagent sessions are silent by default (includeSubagents: false).

Configuration

The agent-sound-alerts entry in the profile's cordis.patch.yml. The profile layer replaces the entry's config as a whole rather than merging by field: the bundle's block does not survive, but every key you omit falls back to the plugin's built-in default — so a partial block is fine:

- id: agent-sound-alerts
  config:
    enabled: true            # master switch
    includeSubagents: false  # also play for child subagent sessions
    minIntervalMs: 1000      # pause between repeats of one cue
    testOnStart: false       # true — play all three cues when the plugin activates
    testGapMs: 2500          # pause between check cues
    debugLogFile: false      # true — write diagnostics to debug.log (or your own path)
    # sounds may be omitted entirely — then the built-in light drum taps play;
    # override a cue with an absolute path to a .wav, or false to switch it off:
    # sounds:
    #   taskDone: 'D:\Sounds\done.wav'
    #   cacheOverflow: false
    #   question: 'D:\Sounds\question.wav'

Requirements

• DeepSeek Harness (dsh) >=0.2.2-rc.1 <0.3.0
• Host OS: Windows (PowerShell SoundPlayer, with console::beep fallback), macOS (afplay), Linux (paplay, then aplay)

Installation

• Ask your Harness agent to install the bundle (its plugin_manager tool → install_bundle, target @zaykoff/dsh-sound-alerts@1.4.2); or
• from a terminal: dsh plugin --profile <profile-name> install @zaykoff/dsh-sound-alerts@1.4.2 (pnpm on PATH is required).

The bundle inserts the agent-sound-alerts plugin entry enabled by default; configure it through the entry's config in the profile (see above).

Development checkout

For a working checkout instead of the published package: plugin_manager → install_bundle with the absolute path to the directory. The package installs as a link:, so files changed on disk are picked up without a restart at the next profile recomposition: editing the profile's cordis.patch.yml or any Plugin Manager action (for example, disabling and re-enabling the include:agent-sound-alerts row).