Introduction

The Agent execution of DeepSeek Harness (DSH) is asynchronous. During long-running tasks or background operation, relying solely on console logs can easily cause missed critical state changes. The dsh-windows-notify plugin provides DSH with Windows-native, system-level notification capabilities. Through Toast pop-ups, custom notification sounds, and taskbar bubble badges, it synchronizes Agent runtime status and pending decision prompts directly to the desktop environment.

The plugin is developed as a native DSH profile bundle. It does not modify any built-in package files; after installation or upgrade, restarting DSH makes it effective.

Core Features

  1. Agent turn status notifications
    Monitors changes in Agent status from running to idle. When an Agent completes its current turn or finishes a task, it triggers a system Toast pop-up. Supports “badge-only” mode and merged summary display within a 5-second window.

  2. Decision reminders with badge updates
    When the Agent calls ask_user_question and requires input, a “DSH needs your decision ❓” prompt appears, listing the question and options. After the user answers or cancels, the red bubble badge in the upper-right corner of the system tray icon automatically decreases by 1.

  3. Taskbar bubble badge
    The red bubble in the upper-right corner of the system tray icon displays both the number of “pending decisions awaiting response” and “completed but unread” items. Clicking the tray icon opens the DSH GUI and clears the completed count. After DSH exits, the tray process shuts down automatically via a port watchdog.

  4. Notification sounds and Do Not Disturb
    Four built-in synthesized notification sounds (soft/brisk/calm/crisp) are included. They carry no copyright risk and can be previewed on the settings page. A Do Not Disturb window is supported (including schedules that cross midnight); during this period, badges accumulate only, with no pop-ups or sounds. It can also follow Windows Focus Assist or system Do Not Disturb mode to stay silent.

Installation and Enablement

The installation command is as follows, adding the plugin to the specified DSH Profile:

dsh plugin --profile web add dsh-windows-notify

After installation or upgrade, DSH must be restarted to load the new plugin configuration and patch.

Configuration and Usage

Settings Page Configuration

The plugin adds a “Notifications” section to the DSH settings page, with the namespace dsh-notify. Changes take effect immediately after saving.

Setting Default Description
sound soft Notification sound style: soft / brisk / calm / crisp
soundEnabled true Master switch for notification sounds
quietHours.enabled / start / end false / 22:00 / 08:00 Do Not Disturb window (cross-midnight supported)
respectSystemDnd true Follow Windows Focus Assist / Do Not Disturb
completeMode toast Completion notification mode: Toast pop-up / badge-only
completeMerge true Merge completion summaries within a 5-second window

Environment Variable Control

The plugin behavior can be controlled globally through environment variables:

  • DSH_NOTIFY=0: Disable all notifications.
  • DSH_NOTIFY_SOUND=<wav path>: Override the default notification sound path.
  • DSH_NOTIFY_MIN_INTERVAL_MS: Sets the notification throttling interval (prevents high-frequency pop-ups).

Technical Architecture and Limitations

Plugin Mechanism

The plugin is implemented using the native DSH plugin mechanism:

  • Profile Bundle: Injects dependencies into a Profile composite through the cordis.patch.yml patch layer.
  • Settings namespace: Registers the dsh-notify configuration using ctx.settings.register and persists it to $DSH_HOME/settings.yaml.
  • WebServer routes: Provides /api/dsh-notify/config (read/write configuration) and /api/dsh-notify/preview (sound preview) endpoints.

Technical Implementation

  • Host side: Monitors agent/status events and handles decision reminder logic.
  • Browser side: Loads without a build step through the __ModuleLoader__ factory and reads/writes configuration through its own routes (avoiding DSH whitelist restrictions).
  • Notification core: Uses PowerShell scripts to call the Windows WinRT Toast API and the ITaskbarList3 interface to implement native UI. The scripts are saved with UTF-8 BOM encoding to support Chinese.

Known Limitations

  • Reminders only: The current version only provides notification display and does not support Toast built-in button interactions (due to Windows restrictions on unpackaged apps).
  • Hot-reload limitation: Bundle patches do not support hot reloading; DSH must be restarted after installing or upgrading the plugin.
  • Platform limitation: Only Windows 10/11 is supported. On non-win32 platforms (such as Linux and macOS), all reminder logic is skipped automatically.
  • Data privacy: Configuration and logs are stored only in the local $DSH_HOME directory. The plugin does not connect to the network, has no telemetry, and does not read credentials.

Conclusion

dsh-windows-notify is a plugin focused on improving the Windows user experience for DSH. By using native system notification mechanisms, it addresses the delayed retrieval of information during long-running tasks. If you use DSH on Windows, it is a useful auxiliary tool worth installing.