Preface¶

When using DeepSeek Harness (DSH), sessions may continue running in the background. After minimizing the app or switching to another window, if you rely only on a regular browser tab, completed results and pending items may not be prominently visible.

dsh-unread-dot is a DSH plugin: it displays an unread red dot or numeric badge on the macOS Dock icon, plays a bubble notification sound when a session completes or requires your attention, and automatically clears the badge when you return to the app.

Below, we introduce its positioning, core features, installation and enabling methods, as well as compatibility and security considerations to note before use.

What This Is¶

dsh-unread-dot is maintained by Bing-Bryan, licensed under MIT, with the license noted as MIT © 2026 Bing-Bryan.

It addresses a specific problem: after installing DSH Web as an app in macOS Chrome, it makes the Dock icon serve as a lightweight status notification entry point. Both the badge and notification sound come from the plugin itself, without relying on system notification banners.

Core Features¶

Verified features include:

• Displays an unread red dot or numeric badge on the macOS Dock icon
• Plays a bubble notification sound when a session completes or requires attention
• Automatically clears the badge when returning to the app
• Implemented using the Chrome Badging API (navigator.setAppBadge / navigator.clearAppBadge)
• Uses a dot or number to differentiate between running sessions and unread results
• No permissions, no banners, no system settings
• Subscribes to the DSH session list, maintaining unread/read status
• Only new completion/pending events during minimization or focus loss trigger the badge and notification sound
• When multiple windows are open simultaneously, a cross-window lock ensures the notification sound plays only once

The built-in sound effect bubble.mp3 is based on an audio clip from Pixabay. The Pixabay license permits free commercial use without attribution.

Status Display¶

The plugin uses two types of Dock icon states to distinguish session status:

The corresponding Badging API usage can be understood as:

navigator.setAppBadge(3)   // Numeric badge
navigator.setAppBadge()    // Red dot without number
navigator.clearAppBadge()  // Clear badge

The number expresses unread results, while the red dot indicates that a session is still running.

Prerequisites¶

This plugin relies on the Chrome Badging API, so the following conditions must be met:

• macOS Chrome
• Open DSH Web in Chrome first
• Install DSH Web as a macOS PWA via Chrome menu “More → Cast, save and share → Install app / Install…”
• navigator.setAppBadge only works within an installed Web App context

Compatibility notes:

• Chrome 81+ supports this API
• As of Chrome 152+, badges/notifications are correctly attributed to the Web App itself

Installation and Enabling¶

Installation involves three steps: install the plugin package, add it to the profile bundle list, and restart DSH Web.

First, run the command below to install the plugin into the DSH profile. Here, the web profile is used as an example:

dsh plugin --profile web add github:Bing-Bryan/dsh-unread-dot

The --profile web in the installation command is a README example and not the only designated profile.

Then modify the profile’s package.json, appending the plugin name to dsh.profile.bundles:

"dsh": {
  "profile": {
    "bundles": [
      "dsh-unread-dot"
    ]
  }
}

This step tells DSH Web to load dsh-unread-dot at startup.

Finally, restart DSH Web:

dsh web

After restarting, go to “Settings → Dock Badge & Notifications” for configuration.

Settings and Verification¶

Items available on the settings page include:

• Dock Badge: Controls whether to display a numeric badge when a session completes or requires attention
• Show Activity Dot While Running: Controls whether to display a red dot without a number while a session is generating a reply during minimization or focus loss
• Notification Sound (Bubble): Controls whether to play the built-in bubble sound when a session completes or requires attention
• Test Notification Sound: Plays the bubble sound immediately once clicked, used to verify whether the sound is working

If you are unsure whether the sound is effective, click “Test Notification Sound” first, then decide whether to adjust system or browser audio settings.

Typical Usage¶

A reproducible workflow is:

1. Open DSH Web in Chrome.

2. Install DSH Web as a macOS PWA via “More → Cast, save and share → Install app / Install…”.

3. Execute the installation command:

dsh plugin --profile web add github:Bing-Bryan/dsh-unread-dot

4. In the profile’s package.json, add dsh-unread-dot to dsh.profile.bundles.

5. Restart:

dsh web

6. Go to “Settings → Dock Badge & Notifications” and click “Test Notification Sound” to confirm the bubble sound can play.

After the above steps, when DSH Web is minimized or unfocused and new session completion or attention-required events occur, the Dock icon will display a badge and play the bubble notification sound; upon returning to the app, the badge will be cleared.

Applicable Scenarios and Notes¶

Suitable for the following usage:

• Running DSH Web in macOS Chrome
• DSH Web installed as a PWA
• Preferring Dock badges and low-distraction notification sounds over some notification banners

Points to note:

• The plugin runs with the current dsh process permissions; review the source code and license before installation
• navigator.setAppBadge only works within an installed Web App context; simply opening a regular web page tab may not satisfy the condition
• Old events are not cumulatively re-counted; only new completion/pending events during minimization or focus loss will trigger the badge and notification sound
• When multiple windows are open simultaneously, the cross-window lock ensures the notification sound plays only once

Conclusion¶

The value of dsh-unread-dot lies in bringing DSH session status to the macOS Dock: a red dot appears while running, a number displays for unread results, a bubble notification sound plays upon completion or when attention is required, and the badge clears automatically upon returning to the app.

Related links:

• Catalog page (source: plugin reference): https://www.skillhub.cn/plugins/Bing-Bryan/dsh-unread-dot
• GitHub: https://github.com/Bing-Bryan/dsh-unread-dot