Introduction¶

When executing agent tasks, DeepSeek Harness (DSH) usually keeps running in the background. If you rely solely on the browser’s native notification mechanism, notifications are often lost when the page is in a background tab, a minimized window, or a closed tab. This means developers may miss signals indicating task completion, moments requiring manual decisions, or error messages caused by task failure.

dsh-notify-linux solves this problem. It sends system-level notifications through the main DSH process, ensuring that desktop notifications and alert sounds are delivered on time regardless of the browser window state.

Plugin Overview¶

dsh-notify-linux is a plugin for DSH on the Linux + GNOME platform, maintained by developer Wlaeg. Its core value is: when DSH completes a task turn, requests user selection, waits for tool call approval, or encounters an error, it sends desktop notifications via notify-send and plays alert sounds via paplay or canberra-gtk-play.

Core Features¶

This plugin delivers notifications through the main DSH process and provides the following capabilities:

1. Event Monitoring and Notifications: Monitors four event types, each of which can be configured independently:
   • turnEnd: Task turn ended.
   • question: The model requests user selection.
   • approval: A tool call awaits manual approval.
   • error: An execution step or the entire task turn failed.
2. System-Level Notifications: Uses notify-send (requires libnotify) to send notifications. The notification title and content include session information (workspace · session ID).
3. Sound Alerts: Plays alert sounds with paplay. If paplay is unavailable, it falls back to canberra-gtk-play.
4. Browser Fallback Mechanism: When system notification capability is unavailable, it uses Web Notification and Web Audio as fallbacks to ensure notifications are not lost.
5. Flexible Configuration: All toggles (including the main switch, event switches, system notification switch, sound switch, and more) can be managed through the “Task Notifications” navigation item on the DSH settings page or by directly editing the JSON configuration file.

Installation and Activation¶

This is a DSH Cordis plugin package. Please install it through the DSH plugin manager.

Run the following command in the terminal to point the plugin to a local directory or Git repository:

# 方式一：指向本地目录
plugin_manager install_bundle /home/wlaeg/文档/deepseek-harness/default-workspace/dsh-notify

# 方式二：指向 Git 仓库
plugin_manager install_bundle https://github.com/Wlaeg/dsh-notify-linux

After installation, the plugin is activated. To enable the browser-side components (settings page, toast notifications), refresh the DSH Web UI page.

Configuration and Usage¶

Configuration File¶

All configuration options are stored in a single JSON file:

$DSH_PROFILE_DIR/dsh-notify-linux

By default, this file is located at ~/.dsh/profiles/web/dsh-notify-linux.json. The configuration file uses an atomic write mode and can be edited and saved directly.

Settings Page¶

In the DSH settings page, navigate to the “Task Notifications” section. It includes the main switch, independent switches for the four event types, system notification/sound switches, theme selection, and a “Test” button. The settings page supports Chinese and English localization.

Environment Requirements and Notes¶

System Dependencies¶

• Platform: Linux + GNOME (verified in Manjaro GNOME and Wayland environments).
• Runtime Environment: Node.js version 22 or higher.
• External Tools:
  • notify-send (from libnotify).
  • paplay (from pulseaudio-utils) or canberra-gtk-play (from libcanberra).
  • Sound file path: /usr/share/sounds/freedesktop/stereo.

Notes¶

• Background Operation: Notifications are sent by the main DSH process, so they remain effective even if the browser page is closed.
• Language: The notification strings are currently in Chinese.
• Plugin Replacement: To replace an installed plugin copy (for example, after modifying source code), the DSH host process must be restarted. Refreshing the Web UI page alone is not enough; old routes and handlers will continue running.
• Optional Dependencies: The plugin supports graceful degradation. If the system lacks notify-send or paplay, the plugin does not block task execution; instead, it falls back to browser-side Web Notification and Web Audio.

Summary¶

dsh-notify-linux uses system-level notifications to solve the problem of delayed or missed feedback when DSH runs in the background. It provides clear feedback for four event types and supports flexible configuration, making it suitable for developers who need to run DSH tasks for extended periods on Linux.

• GitHub Repository
• Community Directory