Skip to main content
Z

dsh-windows-notifications

zjm960929/dsh-windows-notifications

Shows a Windows notification when a turn finishes, an approval waits, or a question needs your answer.

Install

dsh plugin --profile web add github:zjm960929/dsh-windows-notifications

README

dsh-windows-notifications

Windows notifications for DeepSeek Harness — know when a session needs you, and switch each notification type from the plugin page.

npm version npm downloads license Node DeepSeek Harness

English | 中文

dsh-windows-notifications is a DeepSeek Harness Host plugin that raises a native Windows notification when a turn finishes, a tool approval waits, a question waits, or the account needs sign-in. Each type has its own switch on the plugin page, so you do not have to edit a configuration file to mute one kind of alert.

It is for people who start long-running sessions and then look away: the notification lands in the Windows notification center, attributed to DeepSeek Harness, and clicking the toast does not steal focus.

Source: DeepSeek Harness · Primary channel: Windows toast · Scope: root sessions only

Contents

Features

  • Four switchable notification types — turn finished, approval needed, question waiting, sign-in required; each one is a switch on the plugin page.
  • Changes apply immediately — toggling a switch writes the value into the profile configuration and reloads the plugin; no DSH restart.
  • Native Windows surface — real toasts in the notification center, attributed to DeepSeek Harness, with sound control.
  • Click to wake — clicking a toast opens dsh://open, so the DSH window comes forward instead of staying behind other apps.
  • Update alerts — checks npm at startup and raises one notification when a newer version exists; a switch on the plugin page turns it off.
  • Repeat reminders — approvals and questions remind you again on a configurable interval until handled, pause while the session is focused and resume when focus is lost; a finished turn reminds you only until you have seen it, and one focused look retires it.
  • Quiet about delegation — only root sessions notify; turns of delegated subagents never interrupt you.
  • Turn-aware content — completion notices carry the session title and the start of the answer; failures carry the error message.
  • Three delivery channels — a WinRT toast through Windows PowerShell, an Electron notification when the Host exposes it, and a tray balloon as the last resort.
  • Bilingual text — notifications and the settings card follow the active DSH language (Chinese / English).
  • Diagnostics on demand — one log file records event kinds, channel and errors, never message text.
  • A manual tool as well — the model can call windows_notification to raise a heads-up the automatic triggers would not cover.
  • No runtime dependencies — only Node.js built-ins and Windows PowerShell 5.1, which ships with Windows.

Requirements

  • DeepSeek Harness 0.2.x (Desktop or Web). The verification target is 0.2.2-rc.1 on Desktop.
  • Windows 10 or 11 with PowerShell 5.1 (powershell.exe) available.
  • Node.js 22+ for the Host half; the browser half runs in the DSH page.
  • No additional runtime dependencies.

Installation

From the DSH Plugins page

Open Plugins in DSH, search for dsh-windows-notifications, and install it. Reload the page once so the browser half loads.

From the CLI

dsh plugin --profile desktop add dsh-windows-notifications

Use the profile you actually run, for example --profile desktop.

From a local build

pnpm pack
dsh plugin --profile desktop add ./dsh-windows-notifications-<version>.tgz

A tarball install is a package copy, not a symlink. It replaces a same-name npm install until you restore the published package.

Usage

  1. Open Settings → Plugins and select DSH Notification for Windows.
  2. The plugin page shows Notification types with one switch per type.
  3. Toggle a type and keep working; the switch saves right away and the plugin reloads with the new value.

The switches are the normal way to control this plugin. You only need the configuration table below for advanced options or for a headless profile.

Notification types

EventTitleBody
A turn finishes normally (turn/end = completed)Task completeSession title, then the start of the answer
A turn fails (error)Task failedSession title, then the error message
The output limit is reached (max-tokens)Output limit reachedSession title
A tool call waits for approvalApproval neededSession title, then the reason in the UI language
A question waits for an answerWaiting for your answerSession title, then the question
The account needs sign-inSign-in requiredA sign-in hint
The model calls windows_notificationThe given titleThe given body

Aborted or interrupted turns stay quiet, and identical notifications are de-duplicated within 1.5 seconds.

Settings

The four switches map to the first four keys; every key can also be set by hand:

- id: windows-notifications
  name: dsh-windows-notifications
  config:
    turnEnd: true
    approval: true
    question: false
    signIn: true
KeyDefaultMeaning
turnEndtrueNotify when a turn finishes, fails, or hits the output limit
approvaltrueNotify while a tool approval waits
questiontrueNotify while a question waits
signIntrueNotify when the account needs sign-in
previewtrueInclude the start of the answer in completion notices
previewLength120Preview limit in characters (0–400)
skipWhenFocusedfalseStay quiet while the DSH window is focused; only works when the Host exposes Electron windows
silentfalseDo not play the notification sound
openOnClicktrueClicking a toast opens dsh://open to bring the DSH window forward
updateChecktrueCheck npm at startup and notify when a newer version exists
repeatRemindertrueRepeat approval, question and finished-turn reminders
repeatIntervalMinutes5Minutes between repeats (1–60)
fallbacktrueTry the remaining channels when the preferred one fails
transportautoauto / electron / toast / balloon
localeautoauto / zh / en notification language
dedupeMs1500De-duplication window for identical notices
appUserModelIdcom.deepseek.dshWindows app identity used as the notification source
balloonAppUserModelIdtrueStamp the same identity on the tray-balloon fallback
diagnosticstrueWrite the diagnostics log
logFile$DSH_HOME/windows-notifications.logDiagnostics log path

Delivery channels

  1. toast — a WinRT toast raised by Windows PowerShell 5.1. This is what DSH Desktop uses: the notification is attributed to DeepSeek Harness and appears in the notification center.
  2. electron — used only when the Host itself can reach the Electron API; it also brings the window forward when the toast is clicked.
  3. balloon — a tray balloon through System.Windows.Forms, used when both channels above fail. It borrows DSH's app identity so the source name stays DeepSeek Harness when Windows accepts it.

auto tries the channels in that order. The app identity must match the installed Start-menu shortcut, or Windows rejects the toast; the plugin then falls back and remembers the result.

Diagnostics

When a notification does not appear, read %USERPROFILE%\.dsh\windows-notifications.log:

2026-11-11T17:33:58.885Z question event
2026-11-11T17:34:02.059Z shown kind=question transport=toast

The log records event kinds, channel and errors only, never message text. It rotates at 512 KiB to windows-notifications.log.1. A suppressed type shows up as skip kind=question reason=disabled.

Manual notification tool

The Host registers a windows_notification tool so the model can raise a heads-up the automatic triggers would not cover:

{ "title": "Build finished", "body": "The Windows package is signed.", "channel": "toast" }

channel is optional (auto / electron / toast / balloon). The tool result reports the channel that delivered the notice, or why it was not delivered.

How it works

The plugin has a Host half and a browser half:

┌────────────────────────────────────┐
│ Plugin page (React switches)       │
│ turn / approval / question / login │
└───────────────┬────────────────────┘
                │ owner-only HTTP
┌───────────────▼────────────────────┐
│ Host API                           │
│ /windows-notifications/api/config  │
│ read + save via configEditor       │
└───────────────┬────────────────────┘
                │ PowerShell 5.1
┌───────────────▼────────────────────┐
│ Windows toast / Electron / balloon │
└────────────────────────────────────┘
  • The browser half registers a card in the plugins.bundle.config slot, keyed by the package name, so it renders only on this plugin's page.
  • The Host half serves GET/POST /windows-notifications/api/config behind connection.admit() and an owner check; a save goes through DSH's configEditor, which rewrites the profile row and reloads the plugin.
  • Notification delivery runs through one serialized queue, capped at eight pending notices, so a burst of events cannot spawn a PowerShell process per event.
  • There is no build step; index.js and client.js are the shipped files.

Safety and limitations

Safety

  • Every settings request passes connection.admit() and requires an owner peer; unauthenticated requests get 403 and a save is never attempted.
  • Only the four type flags are accepted from the page; unknown keys and non-boolean values are ignored.
  • The HTTP route is same-origin only and is registered on the existing DSH server; the plugin opens no additional port.
  • The plugin never reads message content for its own storage; the diagnostics log records event kinds and delivery outcomes only.

Limitations

  • Whether a toast appears is up to Windows: Do Not Disturb, focus assist, or a disabled app entry can suppress it.
  • Clicking a toast brings the DSH window forward through the dsh: protocol, but it does not open the session that sent the notification: Windows provides no activation callback to an unpackaged app without a registered COM activator.
  • skipWhenFocused has no effect when the Host exposes no Electron window, which is the case on DSH Desktop today.
  • The tray-balloon fallback is attributed by the OS; when the explicit app identity is refused, the source still reads Windows PowerShell.
  • The plugin does not aggregate sessions across multiple Hosts or devices.
  • Update alerts need access to the npm registry; a failed check is written to the diagnostics log and never shown as a notification.
  • A repeated reminder for an approval or question is held while the session is focused and resumes when focus is lost; a finished-turn reminder stops as soon as that session is focused. Both stop when the approval or question settles, when the session sees new activity, when no focus report arrives for 20 seconds, or after six repeats.
  • The internal HTTP route may change between minor releases.

Development

Repository layout

index.js            Host half: events, delivery, settings route, tool
client.js           browser half: notification-type switches
cordis.patch.yml    bundle row inserted into the DSH profile
locale/
  en.json           Plugins-page display metadata
  zh.json
icon.svg            plugin icon
README.md           English documentation
README.zh.md        Chinese documentation

There is no build step. Edit index.js or client.js directly and reload the page after a client change; a Host change reloads the plugin.

Checks

node --check index.js
node --check client.js

Local package smoke test

pnpm pack
dsh plugin --profile <profile> add ./dsh-windows-notifications-<version>.tgz

A tarball install replaces a same-name npm install; restore the published package when the smoke test is done.

Releasing

Releases are published by .github/workflows/publish.yml when a v* tag is pushed. The workflow checks that the tag matches package.json and publishes with npm provenance using the NPM_TOKEN repository secret.

npm version patch
git push --follow-tags

Do not publish manually from a workstation; let the workflow own the release.

Contributing

Issues and pull requests are welcome. Keep changes focused on this plugin, run the checks above, and update README.md and README.zh.md together when behavior or UI text changes.

License

MIT

Related plugins