DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

Dynesshely /

Dynesshely/dsh-plugin-notify

Topic repository only

Notification plugins for DeepSeek Harness (DSH) — sound and desktop alerts when a session actually needs you.

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@7a6eb499

session-notifier — a desktop notification plugin for DeepSeek Harness

License: MIT DSH plugin Version 1.0.0 68 tests passing Node >= 20 PRs welcome

Introductions

A notification plugin for DeepSeek Harness (DSH): when a session genuinely needs you, it plays a chime and shows a desktop notification.

The hard part is not raising an alert — it is knowing when not to. A turn ending is not the same thing as "your turn". Goal loops, scheduled work and queued follow-ups all start the next turn by themselves, and when a subagent finishes, the conversation actually waiting on you is the one that spawned it. Plug a naive "turn ended → notify" rule into that, and it rings through an entire chain of automatic continuations until you turn it off — which is the same as having no plugin at all.

So the plugin runs a decision table:

What happened in your session What you get
A question, an approval request, a plan review Notify immediately (it is asking; there is nothing to wait for)
A turn ended and the session really stopped Wait out a 1.2 s quiet window; 15 s if the session carries an active goal
A loop / goal round continued on its own Silent: a resumption inside the window discards the candidate
A subagent (including an Agent Teams teammate) finished Silent by default (the parent reports the outcome; can be enabled)
A subagent stopped to ask or request approval Notify (only you can move it; labelled Subagent <name>)
You are already looking at that session (window focused + in the main view) Skip (evaluated at delivery time, not when the candidate is registered)
You went back and typed into the session Its stale notification is retired automatically

The two quiet windows are measured, not guessed. Grouping the local DSH session logs by what woke the next turn shows goal rounds resuming at p99 ≈ 375 ms (the 1.2 s window absorbs 100% of them), while human hand-over sits at a median around 6 minutes — two to three orders of magnitude apart, so this can be decided rather than predicted. The script that recomputes it is tools/probe-round-cadence.mjs, and you can run it on your own machine.

Two delivery channels are independent of each other: a Web Audio chime synthesised at runtime (different two-note patterns for interactions and completions, 900 ms cooldown) and a desktop notification. On Windows there is a gotcha worth knowing: a toast tag longer than 16 characters makes the system reject the toast silently, so tags are shortened and made unique.

Why the repo holds a single plugin. This used to be maintained as two implementations, one per "desktop / server" line. Auditing both showed there is no platform-level difference — the Host half is an empty stub in both, they inject the same set of Client services, and both deliver through the same Web Audio + Notification path; the only Electron-specific feature was a line of diagnostic copy. Dual maintenance only bought behaviour drift and the same bug fixed twice, so they were merged into the single session-notifier/ at the repo root. The clients/desktop and clients/server branches remain as historical archives and are no longer updated.

Changes take effect immediately: the plugin is a pure client half (the Host half is empty), so editing it only needs a page refresh — no DSH restart.

How to Install

Requires DSH Desktop; the plugin declares the web platform and rides along with the desktop app's page.

Install it through DSH's plugin manager, pointing at the absolute path of that directory:

plugin_manager install_bundle  ->  <repo path>/session-notifier
plugin_manager remove_bundle   ->  dsh-session-notifier

To make source edits take effect immediately, install with link: (DSH then symlinks it into the profile's node_modules), after which editing client.js only needs a page refresh.

Once installed, find the settings page under Settings → Session reminders (it is also registered as a tab under Settings → Plugins → Session reminders):

  • Channels: master switch, sound, desktop notification
  • Scope: stay quiet for the session on screen / also remind when a subagent finishes / also remind when a subagent needs you
  • Title templates: question, plan review, approval and completion; {session} is replaced with the session name, and an empty template falls back to the built-in copy
  • Test and status: test now, test after 10 seconds, permission state, last alert and diagnostics

The plugin has zero runtime dependencies, no build step, and needs no npm install.

How to Contribute

# Only Node >= 20 is required; there are no third-party dependencies
node session-notifier/tools/test-session-notifier.mjs   # behavioural tests, 68 checks
cd session-notifier && npm run check                    # syntax check across five files

The tests run on a controlled clock: completion alerts are deferred until a session proves it stopped, and without controlling time you cannot verify "hold the candidate and watch what happens next". When you add a decision rule, add its cases to that same table instead of asserting on implementation details.

Before you open a PR, please make sure:

  1. The behavioural tests pass, and the new behaviour has its own checks
  2. Do not hand-roll what a mature library already does (chimes, markdown, icons all have solid implementations)
  3. Any change to a decision condition comes with evidence — justify the threshold, the window and the signal source, and measure it where you can
  4. Commit messages follow conventional commits; this repository writes the subject in Chinese, with a body that explains motivation and trade-offs, not just what changed

Flow: fork → branch from main → commit → open a PR. For behaviour changes, describe what happened before, what happens now, and how you verified it.

Implementation details (signal sources, settings migration, degradation paths, verification boundaries) live in session-notifier/README.md.

Structure

dsh-plugin-notify/
├── docs/
│   └── assets/
│       ├── banner.svg          # source of the poster above (hand-drawn SVG)
│       └── banner.png          # rendered from that SVG; this is what the README uses
├── session-notifier/           # the single maintained plugin
│   ├── package.json            # bundle manifest: dsh.bundle.patch + dsh.client
│   ├── cordis.patch.yml        # inserts the plugin row into a profile
│   ├── index.js                # Host half, empty stub (all decisions happen in the page)
│   ├── client.js               # browser half: decisions, chime, toasts, settings page, console API
│   ├── locale/{zh,en}.json     # title and description shown by the plugin manager
│   ├── tools/
│   │   ├── test-session-notifier.mjs    # behavioural tests on a controlled clock (68 checks)
│   │   ├── probe-round-cadence.mjs      # recomputes the 1.2 s / 15 s thresholds
│   │   └── lib/session-log.mjs          # frame-splits session logs (one zstd frame per line)
│   └── README.md               # triggers, settings, migration, verification
├── LICENSE
└── README.md

The clients/desktop and clients/server branches are pre-merge archives; new code only lands on main.

Star History (Dark Mode)

Star History Chart

License

MIT © 2026 Dynesshely

—/ 5

No ratings yet

Manifest verification required

Commit 7a6eb499814c

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout