Introduction¶
When running long tasks in DSH, progress is often only visible in the main interface or logs, requiring your eyes to scan back and forth. If you are used to tiling your window into another workspace, you might easily mistake the task for being stalled. dsh-hud is a community-maintained client plugin that floats “chat bubble” style notifications from the screen edge using an independent transparent window. It hooks events like THINKING, WORKING, STEP DONE, and COMPLETED to the local DSH session/event, requiring no extra network reporting. Below is an introduction to what it does, how to install it, and in what environments bubbles will appear.
What is it¶
- Name:
dsh-hud(npm package name), repository nuclearmilk/dsh-hud - Maintainer: nuclearmilk
- Category: Client (registers a “Task Notification Stream HUD” page in the settings sidebar; desktop version is carried by an independent Electron process)
- License: MIT (consistent with README and
package.json; version in materials is 1.5.1) - Positioning: Cappella-style water-glass bubble HUD for reporting task progress to DeepSeek Harness
Bubble data flows only between local processes; the control interface listens on 127.0.0.1:52399, and the configuration is written to dsh-hud-config.json under the Electron userData.
Core Features¶
Four Types of Progress Bubbles¶
The plugin displays four states based on session events (as defined in the README):
| Status | Key Behaviors |
|---|---|
THINKING |
Auto-fades out after about 7 seconds |
WORKING |
Persistent throughout |
STEP DONE |
Short sentence summary |
COMPLETED |
Output summary |
Visuals & Interaction (Adjustable in Settings Page)¶
- Light/Dark dual themes; transparency 20%–100% changes in real-time when dragged
- Draggable in move mode; coordinates are remembered after locking
- Avatar: Monet gradient, solid color (color wheel or forms like
#8b5cf6), local image - Local installed font search and switching
allRight: Alternates left/right when closed; aligns neatly to the right when enabled
Long Tasks & Fallback¶
- Persistent “In Progress”: Shows “Task in Progress · Runtime mm:ss” if not finished; can be toggled off in the settings page; enabled by default
- Silent Fallback: Automatically collapses and leaves a note if no progress events occur beyond a set duration (default 45 minutes), preventing bubbles from hanging when the host is abnormal
Runtime Self-Contained¶
The desktop version is ready to use after installation; no need to pre-install Electron, nor do you need plugins like dsh-pet. When the runtime is missing, the plugin pulls it from a mirror (README example is electron 43.3.0, approx 138 MB for the first time, then reused from ~/.dsh/electron/). You can optionally use environment variables DSH_HUD_ELECTRON, DSH_HUD_ELECTRON_MIRROR, DSH_HUD_ELECTRON_DIR, or DSH_HUD_ELECTRON_VERSION to specify path, mirror, directory, or version.
If no Electron executable files can be obtained, the DSH main process will still run, just without desktop bubbles; logs will show WARN and there will be an orange prompt in the settings page.
Installation & Activation¶
Desktop (Windows / macOS / Linux App, Recommended)¶
The desktop profile is exclusively managed by the Electron application and cannot be managed via the command line. Please use the interface to install:
- Open DSH → Settings → Plugins → Add Plugin
- Select Git for installation method, paste into the input box (do not include angle brackets or Chinese instructions):
https://github.com/nuclearmilk/dsh-hud
- Click Install, wait for progress to complete
- Restart DSH (the bubble is an independent Electron process, launched by the host during startup)
- The appearance of the “Task Notification Stream HUD” page in the settings sidebar indicates successful installation
You can also install using the download address dsh-hud-<version>.tgz from Releases. Example for pinning a version:
https://github.com/nuclearmilk/dsh-hud#v1.5.1
You can also write a commit hash after #; if not written, it installs the latest code from the default branch.
Command Line (Non-desktop profile only, e.g., tui)¶
--profile is required:
dsh plugin --profile tui add https://github.com/nuclearmilk/dsh-hud
Executing this on desktop will result in an error: profile "desktop" is managed exclusively by the Electron application.
For local development, you can use link:
dsh plugin --profile tui add link:/path/to/dsh-hud
Update & Uninstall¶
| Operation | Method |
|---|---|
| Update (Git / link) | Uninstall via interface, then reinstall; for link method, run git pull then restart DSH |
| Uninstall | Settings → Plugins → Select dsh-hud → Uninstall → Restart DSH |
Typical Usage¶
- Install and restart on the Desktop DSH as described above.
- Open the Task Notification Stream HUD settings page and adjust theme, transparency, position,
allRight, persistent in-progress, silent timeout duration, etc., as needed. - Initiate session tasks normally on local DSH; bubbles pop up at the screen edge following
session/event. No need to start the HUD process separately.
If the settings page exists but there are no bubbles on the screen: common when the host is not an Electron desktop (CLI / web profile). No extra handling is generally needed for the desktop version; the README states that bubbles will not appear in non-desktop environments.
After updating, the interface remains the same: old bubbles might be detached processes occupying port 52399; starting from 1.4.2, a /api/quit request is sent to the old instance during startup. If it still behaves abnormally, you can manually terminate the residual electron process and then restart DSH.
Suitable Scenarios & Notes¶
Suitable for: People who frequently run agents / long-step tasks on desktop DSH, want to see progress out of the corner of their eye, and do not want to switch back to the main window.
Notes:
- The plugin runs with the permissions of the current DSH process; it is recommended to read the repository source code and the MIT license before installing.
- The community directory skillhub.cn is an independent site with no official affiliation to DeepSeek / Huafang; star counts and other metadata are based on real-time data from each site (clues in materials indicate 0 stars).
- No internet connection or reporting required; it will still pull the Electron runtime locally (if not already present).
Conclusion¶
dsh-hud translates DSH session progress into bubble notifications at the screen edge, featuring “In Progress” timing and timeout collapse for long tasks without events. The desktop version includes built-in Electron retrieval logic. For details and troubleshooting tables, please refer to the repository README.
- Directory page: https://www.skillhub.cn/plugins/nuclearmilk/dsh-hud
- GitHub: https://github.com/nuclearmilk/dsh-hud
