Preface

During DeepSeek Harness (DSH) agent execution, in addition to console logs, there is a lack of immediate auditory feedback for key states. The dsh-agent-sound-alert plugin monitors DSH Agent lifecycle events (such as completion, approval requests, and abnormal interruptions) and plays macOS system sound effects at the corresponding moments, helping users quickly capture Agent status in multitasking or silent environments.

Plugin Introduction

This is a DSH plugin for the macOS platform, maintained by moonlin1213. It obtains Agent status through the Host session event firehose and invokes the local afplay tool to play system preset or custom sound effects.

Core positioning: macOS sound notification plugin
License: MIT
Distribution method: GitHub source plugin (package.json is marked as private: true and is not published to npm)

Core Features

  1. Lifecycle event monitoring: Monitors turn/end (completion, error, abort, limit exceeded) and approval/asked (approval request) events.
  2. System sound playback: Plays default or custom macOS system sound effects (such as Glass, Tink, Basso, etc.) according to different events.
  3. Configuration options:
    - enabled: master switch.
    - volume: volume range 0 to 1 (default 0.7).
    - approvalDebounceMs: approval debounce time, preventing sounds from being too frequent within the same session (default 2500 milliseconds).
    - includeSubagents: whether to include notifications for subagent sessions.
    - onCompleted, onApproval, onError, onAborted, onMaxTokens: supports system sound names, absolute audio file paths, or none.
  4. Test command: Provides the agent_sound_alert_test command, which can be passed completed, approval, error, aborted, or a system sound name for testing.

Installation and Enabling

Because the repository is marked as private, it cannot be installed through regular npm and must be installed using the DSH-provided plugin distribution command.

  1. Clone the repository and ensure the lib/ directory exists (the source repository already includes the prebuilt lib/ folder):
   git clone https://github.com/moonlin1213/dsh-agent-sound-alert.git
   cd dsh-agent-sound-alert
   # 如果修改了源码，需运行 build 脚本生成 lib/
   # npm install --legacy-peer-deps
   # npm run check
  1. Install the plugin using dev_install_package:
   dev_install_package /absolute/path/to/dsh-agent-sound-alert
  1. Enable it in DeepSeek Harness:
    Open Settings → Plugins → Plugin configuration → agent-sound-alert and turn on the enabled switch.

Development and Debugging

If you are in the development stage, you can use dev_inject_plugin for hot loading:

dev_inject_plugin /absolute/path/to/dsh-agent-sound-alert

Note: This command writes registration information to ~/.dsh/super-injector/registry.json and persists the restoration after restart.

If switching to a standard installation, first remove the development injection, then perform the standard installation:

dev_uninject_plugin dsh-agent-sound-alert
dev_install_package /absolute/path/to/dsh-agent-sound-alert

Do not simultaneously retain both dev_inject_plugin registration and dsh.profile.bundles registration, otherwise it may cause configuration conflicts.

Notes

  • Platform limitation: Supports macOS only; depends on the built-in afplay command and the /System/Library/Sounds sound library.
  • Privacy and network: Does not generate any network requests, does not collect telemetry data, and only reads local session events.
  • Concurrency limitation: Supports at most three concurrent playback processes; all active players are stopped when the plugin is unloaded.
  • Event filtering: Specific events such as user-initiated cancellation and crash recovery replay do not trigger sound by default.