Introduction

When running long tasks in DSH Web GUI, users usually do not stare at the page: they switch to other tabs to write code or read documentation, letting the task proceed in the background. The problem arises when the session requires human intervention—when pending approvals, plan approvals, or model questions arrive, the page itself is silent. The task stops in place until someone switches back and notices.

dsh-web-notify solves this attention gap. It is a client-side plugin mounted on the web profile: when pending interactions arrive, it uses multi-channel alerts via audio, tab titles and Favicon badges, OS notifications, PWA taskbar badges, and Dock notifications. It also provides corresponding alerts for session completion, task failure, disconnection/reconnection, and model/tool runtime exceptions (429 quotas, etc.). DeepSeek Harness’s philosophy is “everything is a plugin,” and dsh-web-notify is a typical implementation of this form. The following introduces it in order of features, installation, configuration, and debugging.

What is it

First, let’s cover the basic information. dsh-web-notify is maintained by renpengfei1027, under the MIT license, current version 0.1.5. It is in a pure plugin form: host half (lib/index.js) + client half (lib/client.js, loader format), mounted into dsh web via a profile patch. Regarding dependencies, the runtime dependency is @deepseek-ai/schemastery ^3.18.1, and the peer dependencies are @deepseek-ai/cordis, @deepseek-ai/dsh-api-remotes, @deepseek-ai/dsh-settings, and react.

Pending Approvals / Plan Approvals / Question Arrival

This is the plugin’s main scenario. Triggered when any session has pendingInteraction, there are a total of six channels:

  1. Audio: A WebAudio-generated E5-G5-B5 arpeggio;
  2. Tab Title Badge: Uses MutationObserver to counteract the shell’s title writing, ensuring the badge isn’t overwritten;
  3. Tab Favicon: 32×32 badge;
  4. OS Notification: Deduplicated by session tag; clicking jumps to the corresponding session and focuses the window; for approval types, it uses requireInteraction to persist the notification;
  5. PWA Taskbar Badge: Displays a number on the taskbar/app icon via navigator.setAppBadge;
  6. Dock Notification Center: Real-time counter in the bottom-right FAB, expanding the panel lists all pending items.

Two design details are worth mentioning separately.

The first is Session Degradation: When the page is visible and a new approval belongs to the currently open session, audio and OS notifications are silenced, keeping only visual channels—eyes are on this session, so sound is redundant. In all other cases, all channels work normally.

The second is Deduplication: No repeated alerts for the same (session, kind) within the cooldown period. The cooldown duration is controlled by cooldownMs, default 5s.

Completion, Failure, and Runtime Exception Alerts

Besides approvals, the plugin also covers four event types:

  1. Session/Sub-agent Completion: Completion toast card + soft beep + optional OS notification; when the page is hidden, the toast is invisible, so it is replaced with tab title pulse + PWA badge + audio + OS notification.
  2. Task Failure: When job status is failed / killed, or completed but detail is non-empty and not exit code: 0, an error variant toast + audio + optional OS notification is displayed; reported only once per job registration number.
  3. Model/Tool Runtime Exception: Captures llm/retry (429 quota/rate limit), error / max-tokens / interrupted from turn/end, and error / isError from tool/result. An error variant toast (truncated to 240 characters of the original error text) + audio + optional OS notification is displayed.
  4. Disconnection/Reconnection: When disconnection lasts longer than connectionAlertAfterMs (default 10s), a warning toast + audio is reported; on recovery, a light toast + completion beep is reported; fast blinks/disconnections are not reported.

Sub-agent Coverage and Boundaries

The detection pipeline covers all session lines, including sub-agents. Boundaries need to be clear: based on DSH’s current delegation semantics, delegated sub-agents do not generate pending approvals/questions, so no pending items for sub-agents appear; however, completion, failure, and exception alerts for sub-agents still work normally and won’t be missed.

Installation and Enablement

Prerequisites

  • Node.js >= 22;
  • pnpm: dsh plugin uses pnpm to install dependencies internally, run npm install -g pnpm first;
  • dsh CLI: When not installed globally, prefix all dsh commands with npx @deepseek-ai/dsh, e.g., npx @deepseek-ai/dsh plugin --profile web add dsh-web-notify.

Two Installation Methods

npm one-click mount:

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

DeepSeek Harness is currently in a development preview rapid iteration phase; the README recommends mounting the local repository in development/debug mode with link::

git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify
npm install
npm run build
dsh plugin --profile web add link:$(pwd)
# Windows PowerShell: dsh plugin --profile web add link:$PWD.Path

After installation, restart dsh web, and a “Notifications” card will appear under “Plugin Configuration” on the settings page.

Whitelist Settings Namespace

DSH officially hardcodes the settings whitelist (WEB_SETTINGS_NAMESPACES) in the package, currently not open to plugin injection, so you need to run the repository’s built-in patch script to inject notifications into the whitelist:

node scripts/patch-apiproxy.mjs

The script is idempotent and safe to run again; it must be run again after upgrading dsh.

Sandbox Environment Notes

  1. Sandboxes for AI coding tools like TRAE, Cursor usually block writing to ~/.dsh/, while both dsh plugin and dsh web need to write profile files; these two types of commands must be executed in a regular terminal outside the AI tool.
  2. Do not manually npm install into ~/.dsh/profiles/web/node_modules/: this bypasses the dependency linking logic of dsh plugin, causing the settings service to be unreachable and namespace registration to fail silently. Always install via dsh plugin --profile web add.

Configuration and Common Tweaks

After the steps above, the plugin is mounted into the web profile and takes effect with dsh web restart. The settings card is located at DSH Web Settings -> “Plugin Configuration” -> “Notifications”, with 120ms debounce hot reload; changes take effect immediately, no restart needed. OS notification permission is requested for Notification on the next user gesture after the first trigger.

A few common tweaks:

  • Only approval alerts, others off: completion=false, connection=false, jobFailure=false, agentError=false;
  • Night mode quiet: quiet.enabled=true, quiet.start=22:00, quiet.end=09:00, quiet mode only silences, visual channels remain;
  • Find system notification popups annoying: notify=false, keep badge=true, dock=true.

Debugging and Diagnostics

The plugin provides on-device diagnostics. Open DevTools console on the DSH Web page and observe window.__NOTIFICATIONS__:

__NOTIFICATIONS__.applied
__NOTIFICATIONS__.cardRegistered
__NOTIFICATIONS__.feedCounters
__NOTIFICATIONS__.hostStatuses
__NOTIFICATIONS__.jobSamples

Among them, applied and cardRegistered reflect the plugin and settings card mount status, and feedCounters is the counter for various events. If you don’t want to wait for a real approval to verify the effect, you can call demo() / demoSound() to test UI and audio at once.

Suitable Scenarios and Notes

Suitable people: those who run DSH sessions in the background and need to respond to approvals and questions in time; multi-session parallel users who want to view pending items in one panel; PWA users who want to see the pending count directly in the taskbar.

Notes:

  1. The plugin runs with the permissions of the current dsh process; it is recommended to read the source code and license (MIT) before deciding to install.
  2. DSH is in a development preview rapid iteration phase; remember to run node scripts/patch-apiproxy.mjs again after upgrading dsh.
  3. Installation and restart commands must be run in a regular terminal, not in the AI tool sandbox.

Conclusion

To summarize: dsh-web-notify changes DSH Web GUI’s “waiting for someone to look back” to “actively calling someone”—alerts for approvals, questions, completion, failure, disconnection, and 429 all appear at the right places. Channels, volume, and quiet mode can be toggled as needed, configuration supports hot reload, diagnostics are built-in, and the installation cost is low.

  • Community Plugin Directory: https://www.skillhub.cn/plugins/renpengfei1027/dsh-web-notify
  • GitHub Repository: https://github.com/renpengfei1027/dsh-web-notify