When developing agents or orchestrating tasks in DeepSeek Harness (dsh), you often need to monitor task status or wait for manual confirmation. When the window is obscured or you are working in another application, it is easy to miss these critical events. The dsh-notifier plugin solves this by using the operating system’s native notification capabilities to push task completion and approval requests directly to your desktop.

What It Is

dsh-notifier is a system notification plugin for DeepSeek Harness (dsh). It is maintained by YZz-S and released under the MIT license. The plugin primarily addresses the problems of “unclear task execution status” and “easily missed approval flows,” ensuring developers or users can receive DSH status changes promptly when switching windows.

Core Features

  1. Task Completion Notification
    When a top-level session returns from running to idle (i.e., a turn has finished), the plugin sends a “Task completed” notification. The plugin uses agents.roots() to identify top-level sessions, avoiding notification spam when subagents finish.

  2. Approval and Input Notification
    When an approval is triggered (approval/request) or manual in-page input is required, the plugin sends an “Action required” notification and includes the tool name and reason that triggered the request in the body.

  3. Does Not Interfere With the Approval Flow
    The plugin’s notification logic passes transparently through the waterfall’s next(). It does not answer or change approval results and does not affect the existing approval process in any way.

  4. Cross-Platform Support
    * Windows: Supports WinRT Toast notifications, falling back to balloon notifications on failure.
    * macOS: Uses osascript to run display notification.
    * Linux: Uses notify-send.

  5. DeepSeek Harness Branding
    On Windows, the plugin registers a custom AppUserModelID (DeepSeekHarness.Notify), so the system displays “DeepSeek Harness” as the notifying application name and icon.

Installation and Enabling

Installing this plugin requires the DSH command-line tool.

dsh plugin --profile web add github:YZz-S/dsh-notifier

After installation, as long as the dsh process is running, system notifications will pop up automatically when a task completes or manual confirmation is required. The plugin is a pure Host plugin and takes effect without refreshing the page.

Typical Usage

Depending on the use case, there are two ways to enable it.

Option 1: Dynamic Cordis Plugin (Temporary Runtime)

This approach is suitable for temporary enablement during development and debugging, with its lifecycle bound to the current dsh process.

  1. In the Cordis tool in the dsh Web GUI, call cordis_define and paste the contents of host.js into the code.host field. Set plugin.kind: 'new' and choose an idPrefix of 3 to 6 lowercase letters.
  2. Call cordis_run to activate the plugin.
  3. The next time a task completes or an approval is triggered, a system notification will appear.

Note: A dynamic plugin has the same lifecycle as the current dsh process. After restarting dsh, you must define and run it again.

Use the installation command provided above to install it as a formal plugin, so you do not need to manually define it each time.

How It Works

The plugin sends notifications by invoking native OS commands via subprocess.spawn. The command resolution order is:
1. Windows: Prefers PowerShell to invoke WinRT Toast (with a custom AppUserModelID), falling back to balloon notifications on failure.
2. macOS: Invokes osascript.
3. Linux: Invokes notify-send.

The title is fixed as “DeepSeek Harness,” and the body displays the session title plus the status. To prevent excessive notifications, the plugin only sends a task completion notification when it detects that a top-level session (identified via agents.roots()) has changed from running to idle.

Privacy and Cautions

  1. Privacy
    * Only registers an AppUserModelID under HKCU for displaying the source name and icon.
    * Does not perform file writes, telemetry, or persistent storage.
    * Does not collect or upload any local data.
    * On Windows, the icon is fetched from a public CDN (avatars.githubusercontent.com/u/148330874?v=4&s=200) only when displaying a notification.

  2. Limitations
    * Process level: Dynamic plugins use the current dsh process as their lifecycle and must be reloaded after a restart.
    * Service dependency: If the subprocess service is unavailable, the plugin silently disables itself.
    * Network dependency: Icons on Windows depend on the network. When offline, the icon may not appear, but the notification itself will still pop up.

Summary

dsh-notifier solves the problem of delayed information in DSH task execution and approval flows through a lightweight system notification mechanism. It follows the principle of “not interfering with business” while providing immediate feedback, with very low privacy risk and resource usage.