Introduction

When using DeepSeek Harness (DSH) for conversational development or daily use, conversations usually run in the background. If the Web GUI is closed or switched to another window, it can be difficult to know immediately whether a conversation turn has completed. This plugin sends notifications to the macOS system through the Host process, so feedback can be received even when the GUI is not visible.

Core Features

Conversation Completion Notification
The Host process listens for agent/status events and is triggered on the edge transition when the root session changes from running to idle. It uses terminal-notifier to display a system notification with the session name as the title and the assistant reply as the body (titles longer than 60 characters or bodies longer than 200 characters are truncated). Only root sessions trigger notifications; turns driven by subagents and automation are skipped. Clicking the notification does not activate the app window; it only serves as a reminder.

Synthesized Notification Sound
The plugin does not rely on external audio files. Instead, it synthesizes a 16-bit PCM mono WAV notification sound in-process (44.1kHz, 20ms linear attack + exponential decay, 120ms note interval). This sound exactly matches the Web Audio preview parameters in the Settings card, is available offline, and is played via terminal-notifier -sound.

Settings Card
The card is rendered in the settings.general.item slot under “Settings → General” and provides a Chinese/English bilingual interface. It includes an “Enable System Notifications” toggle, a “Play Notification Sound” toggle, a tone selector (soft / crisp / low), and a “Preview Notification Sound” button. This button also serves as a user gesture to trigger browser notification authorization.

Persistence and Fallback
Configuration is written to $DSH_HOME/settings.yaml under the notifications namespace. Before the Host is loaded, fallback is handled using browser monitor + localStorage; after the Host is loaded, it takes over the notification logic to avoid duplicate notifications.

Installation

Before installation, make sure terminal-notifier is installed. This plugin hard-codes the path of terminal-notifier installed via Homebrew (/opt/homebrew/bin/terminal-notifier), so install it using brew install terminal-notifier.

  1. Edit $DSH_HOME/profiles/web/package.json.
  2. Add the dependency in dependencies:
    "dsh-plugin-notifications": "file:<本仓库路径>"
  1. Add the bundle name in dsh.profile.bundles:
    "dsh.profile.bundles": {
      ...
      "dsh-plugin-notifications": {}
    }
  1. Ensure node_modules/dsh-plugin-notifications resolves to this repository.
  2. Restart dsh web. If not restarted, the Host remains unloaded, and only the browser-side fallback logic is available.

Configuration

Configuration can be completed via the Web GUI card or by editing $DSH_HOME/settings.yaml directly. The default values are as follows:

notifications:
  enabled: false   # 一轮对话完成后弹系统通知
  sound: true      # 通知时同时播放提示音
  tone: soft       # 音调: soft | crisp | low

Usage

  1. Open Web GUI → Settings → General → Conversation Completion Notification.
  2. Enable “Enable System Notifications,” and enable the notification sound and select a tone as needed.
  3. Click “Preview Notification Sound” to confirm the sound effect.
  4. On first use, grant notification permission in the macOS system dialog.

Notes

  • Platform Limitation: macOS only.
  • Permission Behavior: Clicking the notification does not activate the app window; it only serves as a reminder.
  • Notification Behavior: The notification only serves as a reminder and does not open any window.
  • Configuration Permission: Configuration is written to $DSH_HOME/settings.yaml. The settings.mutate RPC only allows built-in namespaces; third-party plugins read and write configuration through their own routes GET /notifications/status and POST /notifications/update.

Ecosystem

This plugin is maintained by NattoCB and is part of the DSH ecosystem. It is not an official product of DeepSeek or High-Flyer. The plugin directory and source code can be viewed on GitHub.