Introduction

When running long tasks with DSH, your attention is usually not on that specific window. You switch to the editor to write code or to the browser to look up information. By the time you switch back, the task might have finished, or it might be stuck in permission approval or a question from the agent—when you finally switch back, you realize it should have been handled long ago.

Users of Codex and Claude Code are familiar with a solution to this problem: Hook notifications. When an event occurs, a system-level alert pops up, visible regardless of which window is active. dsh-notifier brings this experience into DSH. DSH’s philosophy is “everything is a plugin,” and notifications are a perfect fit for a plugin to fill.

What is this

dsh-notifier is a DSH task notification plugin maintained by nanami-0713, open-sourced on GitHub (repo nanami-0713/dsh-notifier), and available as the npm package @hsinsekai-nanami/dsh-notifier—note that the two names do not match, so pay attention when searching. Current version 0.5.0, MIT license.

It listens to four types of events, following the “Event → Hook → System Notification” chain, which is isomorphic to Claude Code’s Notification Hook:

  • Task End: agent/status changes from running to idle
  • Permission Approval: approval/requested
  • User Question: ask_user_question
  • Task Error: agent/error

Notifications are divided into three layers: toasts within the DSH web interface, system notification center banners, and cross-window floating panels. Decision-making events (approval, question) use pinned modals waiting for you to handle them; other events disappear automatically after the notification.

Core Features

Three-layer Notification Channels

Web Toast: The dark notification card in the bottom-right corner of the DSH web page, with sound. Uses React portal attached to document.body to ensure it floats above other elements.

System Notification Center Banner: macOS uses osascript, Linux uses notify-send, Windows uses system bubbles. Can be turned off in settings.

Cross-window Floating Panel (Default On): macOS uses the built-in Swift notifier, based on the .floating layer of NSPanel, combined with canJoinAllSpaces and fullScreenAuxiliary. The panel floats above all application windows, all Spaces, and fullscreen applications, with “Go Handle / View Session” buttons.

Decision-type Modal Pinning

Approval and question belong to events requiring your decision. The corresponding modals will stay pinned until you answer or reject on the web side, then they close automatically. Task end and error modals disappear automatically after 10 seconds and do not pile up.

Mobile Sync Notifications

When dsh-remote bridge runs on the PC and the mobile app is connected, the plugin can push two types of PC notifications to the phone: task completion and requests for you to answer (introduced in v0.4). v0.5 adds a toggle: global switch bridgePush plus type-specific switches bridgePushKinds.done and bridgePushKinds.question. There is also an independent receiving switch on the mobile app side, so they don’t interfere with each other.

This path has clear boundaries: it only forwards done (task completion) and question (needs your answer) types; approval and errors are not forwarded for now. The bridge runs over the local area network; there is no public network system-level push channel. Notifications cannot be delivered if the mobile app is not open or the process is killed.

Visual Configuration in Settings Page

Since v0.3, the “Settings → Notification” in the bottom-left of DSH provides visual configuration: 4 built-in presets (default / top-light / focus / native-only). Adjustable toast position, theme, width, border radius, duration, sound, simultaneous count, and system-level switch. Changes take effect in real-time and are saved to ~/.dsh/plugins/dsh-notifier/config.json.

Configuration also supports reading and writing via same-origin API:

GET/PUT /api/dsh-notifier/config

Installation and Activation

Choose one of three methods. After installing, run dsh web for it to take effect.

dsh plugin --profile web add @hsinsekai-nanami/dsh-notifier@0.5.0
dsh web   # 启动或重启后生效

Method 2: GitHub Release Installation

First, download hsinsekai-nanami-dsh-notifier-<version>.tgz from the repository Releases page, then install the tgz directly without extracting:

dsh plugin --profile web add ./hsinsekai-nanami-dsh-notifier-<version>.tgz

Method 3: Source Build Installation

git clone https://github.com/nanami-0713/dsh-notifier.git
cd dsh-notifier
npm install
npm run build:all
dsh plugin --profile web add .

Typical Usage

After installation, verify first, then use daily.

Confirm Notifications Appear

Open the DSH web page, go to “Settings → Notification” in the bottom left, switch presets or modify fields; changes take effect in real-time. Then run a task and observe if toasts and system notifications appear as expected.

Run E2E Acceptance Tests

The repository includes event-level E2E scripts:

node scripts/e2e-done.mjs       # 任务结束
node scripts/e2e-approval.mjs   # 权限审批：面板钉住，处理完自动关闭
node scripts/e2e-question.mjs   # 用户提问
node scripts/ui-test.mjs        # Headless Chrome 全链路截图

After the above steps, the notification chain and web UI for task end, approval, and question events can be confirmed.

Verify Floating Panel is on Top (macOS)

On macOS, you can use CoreGraphics window enumeration to confirm the panel is indeed floating on the screen. kCGWindowLayer == 3 is the .floating layer:

swiftc scripts/winlist.swift -o /tmp/winlist && /tmp/winlist

Disable System-level Popups

If you only want web toasts and notification center banners, you can turn off system-level popups in settings, or set floating to false in the plugin configuration.

Platform Differences and Limitations

Web toasts do not rely on platform capabilities; cross-window system popups choose different implementations based on the platform:

  • macOS: Built-in Swift notifier floating card. Requires Xcode Command Line Tools (swiftc) for first use; automatically compiles and caches to ~/.dsh/plugins/dsh-notifier/DSHNotifier on first trigger. Falls back to osascript display dialog / notification if swiftc is not found.
  • Windows: Uses system PowerShell plus WScript.Shell.Popup, no extra dependencies; popups are in system dialog style and cannot be customized.
  • Linux: Requires installing zenity; falls back to notify-send banner if zenity is missing; popups are also in system dialog style.

Note: The README describes cross-window popups for Windows and Linux but they are not verified on real devices; macOS is the platform verified on real devices. If you encounter issues on other platforms, you can submit an issue to the repo.

Applicable Scenarios and Precautions

dsh-notifier is suitable for these scenarios: long-running background tasks, people who switch between multiple windows or desktops; people who want to track task progress on their phone after leaving their desk and need to work with dsh-remote; people who are not satisfied with just staring at the DSH web page waiting for results.

Three things to note before installation and use:

  1. The plugin runs with the current dsh process permissions. It is recommended to check the plugin source code and license before installing (this project is MIT).
  2. The npm package name @hsinsekai-nanami/dsh-notifier does not match the GitHub repo name nanami-0713/dsh-notifier. Do not treat them as two separate projects.
  3. The macOS cross-window floating panel is the main implementation verified on real devices. The corresponding popups for Windows/Linux have not been verified on real devices. Test them yourself before using them in a production environment.

Summary

Recap: dsh-notifier listens to four types of events (task end, approval, question, error) and reminds you via three channels (web toast, system notification center banner, cross-window floating panel). Decision-type modals stay pinned until handled; task end modals disappear automatically after 10 seconds. It can also push to mobile when paired with dsh-remote; configuration is fully visual and takes effect in real-time.

  • Plugin Directory Page: https://www.skillhub.cn/plugins/nanami-0713/dsh-notifier
  • GitHub Repository: https://github.com/nanami-0713/dsh-notifier

Note that the directory page is a community-maintained independent site, not officially affiliated with DeepSeek or Hyperbolic, and is only used for plugin search.