Preface¶

When running agent tasks with DeepSeek Harness (dsh), a common issue is: the task continues executing in the background while the developer has already switched windows away, with no way to know when the top-level task completes, when it errors out, or whether it’s waiting for sandbox approval or an agent question. Manually watching logs is not a sustainable solution.

Here’s an introduction to a DSH plugin: dsh-win-notify. It displays sound-enabled Toast notifications on Windows, and when a notification is clicked, it tries to bring the existing DSH GUI session to the foreground rather than repeatedly opening new temporary browser tabs.

What This Is¶

dsh-win-notify is a DeepSeek Harness (dsh) plugin maintained by MuziIsabel, licensed under MIT.

It solves the problem of: providing sound-enabled notifications on Windows 10/11 when agent tasks complete, error out, wait for approval, or wait for a reply; clicking the notification prioritizes switching to and displaying the existing GUI tab.

The plugin displays the application name as DeepSeek and uses the official whale icon; notification capability relies solely on Windows’ built-in PowerShell 5.1, requiring no additional runtime installations.

Core Features¶

• Notifies when a top-level agent round completes: triggered when the session agent state transitions from running to idle.
• Sub-agent rounds remain silent, avoiding frequent interruptions from subtask processes.
• Notification body displays the most recent user prompt.
• Configurable to notify when tasks error out.
• Configurable to notify when waiting for sandbox/permission approval.
• Configurable to notify when the agent asks a question via ask_user_question and waits for a reply.
• Focus awareness: if the GUI page is in the foreground and currently displaying the session that triggered the event, notifications for that session are suppressed.
• Manually stopped tasks are not considered completed and do not trigger notifications.
• Clicking a notification prioritizes switching to and brings the existing GUI tab to the foreground; no temporary browser tabs are created; a new tab is only opened when no GUI is alive.
• Falls back to NotifyIcon bubble when identity registration fails.
• Depends only on Windows’ built-in PowerShell 5.1.

Installation and Enablement¶

First, install the plugin in the target profile. Taking the web profile as an example:

dsh plugin --profile web add github:MuziIsabel/dsh-win-notify

After execution, dsh plugin forwards to pnpm within the profile directory, and the bundle merges itself into the profile’s dsh.profile.bundles list.

After installation, restart the profile or let the profile’s HMR take effect to activate the plugin.

If you wish to receive notifications in other profiles, you can install it the same way into profiles such as headless.

Uninstall command:

dsh plugin --profile web remove dsh-win-notify

Typical Usage¶

The plugin inserts the loading line win-notify into the profile. You can override the configuration in the profile’s cordis.patch.yml.

Below is the complete configuration example from the README:

- id: win-notify
  config:
    enabled: true          # Enable plugin (default true)
    sound: default         # default | reminder | sms | alarm | silent
    onError: true          # Also notify when tasks error (default true)
    openOnClick: true      # Open/switch GUI session on notification click (default true)
    directActivate: true   # Prioritize delivering to live local loopback GUI tabs; otherwise use browser deep link
    baseUrl: ''            # Custom GUI root URL (default auto-detects webServer port)
    approval: true         # Notify when waiting for user approval (default true)
    approvalWaitMs: 3000   # How long to wait after approval pending before notifying
    question: true         # Notify when waiting for user reply (default true)
    questionWaitMs: 3000   # How long to wait after question pending before notifying
    suppressWhenVisible: true  # Suppress notifications for the session being viewed (default true)
    visibilityTtlMs: 25000      # Foreground state freshness window (client heartbeats approximately every 10 seconds)
    title: 'DeepSeek Harness'
    body: 'Task completed'
    bodyError: 'Task error'
    maxPromptChars: 64

If you only need to temporarily disable notifications, you can override just enabled:

- id: win-notify
  config:
    enabled: false

If you need to modify prompt length or text, you can override:

- id: win-notify
  config:
    maxPromptChars: 80
    title: 'DeepSeek'
    body: 'Task completed'
    bodyError: 'Task error'

How Notification Click Works¶

For local loopback GUI addresses, the plugin registers the dsh-win-notify:// protocol. When a notification is clicked, it launches a local miniature DeepSeek.exe helper rather than directly opening a browser.

This helper requests the local DSH service to deliver an open-session command to the most recently focused alive GUI tab; the corresponding tab calls sessions.open(id) in place. This avoids full page refresh and doesn’t open new browser tabs.

If successful confirmation is received, the helper also makes a best effort to use Windows UI Automation to select the Chrome/Edge tab matching the title, making it convenient to bring the DSH tab to the foreground while browsing other tabs. Browser windows remain in their current state when maximized or normally sized; only minimized windows are restored.

Note: browser accessibility features, permission levels, virtual desktops, and focus preemption policies may still prevent foreground switching; in such cases, the session has already been selected in the background.

If no alive GUI confirms in time, or the protocol registration is unavailable, the helper safely falls back to the regular <gui>/?session=<id> deep link; the deep link’s BroadcastChannel handoff serves as the second-level fallback.

First-time custom protocol clicks may require a one-time browser/Windows confirmation. Non-loopback custom baseUrl values remain on regular HTTP deep links for security reasons.

Identity Registration and Diagnostic Logs¶

Windows only displays toasts from registered identities. The plugin automatically performs one-time identity registration upon activation:

1. Compiles a miniature DeepSeek.exe placeholder program into %LOCALAPPDATA%\DeepSeek.
2. Creates a Start Menu shortcut DeepSeek.lnk pointing to it, with the multi-size DeepSeek.ico as its icon.
3. Writes the AppUserModelID (DSH.WinNotify) into the shortcut via IPropertyStore P/Invoke.

After registration, notifications display with the DeepSeek name and whale icon.

DeepSeek.lnk is the notification identity carrier and must not be deleted. If missing, the plugin automatically rebuilds it.

The plugin appends every registration attempt and notification to:

$DSH_HOME/dsh-win-notify.log

Applicable Scenarios and Notes¶

Suitable for developers using DSH on Windows 10/11, especially in the following situations:

• Agent tasks often run for extended periods and require reminders upon completion.
• Timely notifications are needed even when tasks error out.
• Reminders are needed to return when tasks await sandbox approval or ask_user_question replies.
• You want to click a notification and return to an existing DSH GUI session rather than continuously opening new tabs.

Notes:

• Environment requirements: Windows 10/11, and any dsh profile (web, headless, tui).
• The plugin runs with the current dsh process permissions, so reviewing the source code and license before installation is recommended.
• Notification identity relies on the Start Menu shortcut DeepSeek.lnk; the plugin rebuilds it when missing, but do not delete it manually.
• If no notifications are received, first check whether DSH.WinNotify is enabled in Windows notification settings, and confirm that DeepSeek.lnk exists.
• The icon originates from the DeepSeek Harness favicon (@deepseek-ai/dsh-web-frontend, MIT © DeepSeek).

Links¶

• GitHub: https://github.com/MuziIsabel/dsh-win-notify
• Search for the plugin name dsh-win-notify in the DSH plugin/community directory.