Preface

DeepSeek Harness runs in a Node.js environment. On macOS, command-line output and desktop interaction are limited. The dsh-macos-notify plugin feeds Harness runtime status back to the system desktop through the native Notification Center and provides a complete set of filtering and sound configuration mechanisms.

Plugin Overview

This plugin provides native macOS notifications, supports event-type-specific sound playback, notification filtering, multi-task merging, and a first-level settings page in the DSH Web UI. It is maintained by CrombastiC and licensed under MIT.

Installation and Enabling

Installation requires only the following command:

npx -y @deepseek-ai/dsh plugin --profile web add dsh-macos-notify

After installation, open Settings → macOS notifications in the DSH Web UI settings navigation.

To remove the plugin, run:

npx -y @deepseek-ai/dsh plugin --profile web remove dsh-macos-notify

Core Features

Event Notifications and Sounds

The plugin triggers Notification Center pop-ups in the following circumstances:
* A task turn has completed
* A task has failed or been blocked
* A task is waiting for approval
* A task has been aborted

Different event types can be configured to use different system sounds. Any event can be muted. In the settings page sound selector, built-in system sounds can be used and previewed in-page using the afplay command. Custom imported sounds are supported: files are converted to AIFF format, limited to 5MB in size and 10 seconds in duration. Up to 20 managed files are allowed, with a total capacity limit of 50MB, stored in ~/Library/Sounds.

Filtering and Merging Strategies

To prevent parallel tasks from flooding the Notification Center, the plugin includes a built-in merging mechanism:
* Merge window: A default 1.5-second merge window; results within this period are consolidated into a single notification.
* Summary mode: Optional periodic summaries.
* Duplicate error suppression: A configurable cooldown window suppresses repeated error notifications within the same session.

Project Rules and Filtering

Project path rules enable fine-grained control over notification behavior:
* Mute: Completely suppress all notifications under the specified path.
* Errors only: Allow notifications only for errors, blocking events, and approval requests.
* Important projects: Bypass filters such as minimum duration, focus, idle time, quiet hours, and temporary pause.

Additionally, the following are supported:
* Minimum turn duration filter: Prevents excessively short response times (default: 30 seconds) from triggering notifications.
* Web tab focus suppression: Suppresses completion notifications when a DSH Web UI tab is focused.
* HID idle-time gating: Requires the keyboard or mouse to be idle for a specified period (default: 0 seconds) before sending a completion notification.

Quiet Hours and Diagnostics

  • Quiet hours: Supports daily local-time quiet hours, with an option to continue sending error and approval notifications during quiet hours.
  • Temporary pause: Supports temporary pauses of custom duration and displays the remaining time.
  • Notification diagnostics: The settings page records the most recent 50 decisions (sent, queued, suppressed, failed) and their reasons. The data is persisted to ~/Library/Application Support/dsh-macos-notify/state.json and remains after restart.

Terminal Support

The plugin supports the OSC 9 notification protocol and is compatible with terminals such as iTerm2, WezTerm, Kitty, Ghostty, and Warp, as well as tmux sessions supported through DCS passthrough.

Notes

  • System limitations: The plugin supports macOS only. Native notifications depend on osascript, and custom sound import depends on macOS audio tools.
  • Sound behavior differences: Over the OSC 9 channel, the terminal controls whether sounds are played and how they are played; at this time, the plugin’s per-event sound selection is ignored.
  • Web settings channel: The Web settings page uses a trusted /macos-notify RPC channel because the current DSH Web settings proxy imposes a namespace whitelist restriction on built-in settings.
  • Sound management: Only sounds imported from v0.2.0 onward are marked as “managed sounds.” Older files manually copied to ~/Library/Sounds remain after plugin removal and must be cleaned up manually.

Conclusion

This plugin addresses the lack of native feedback for DSH on macOS. With richer filtering and sound configuration, it makes task status notifications more controllable. The source code and repository are available at: [GitHub link].