dsh-notification-badge
桌面、浏览器和 webhook 通知，以及 DeepSeek Harness 的应用图标提示徽章——了解您的代理何时完成一轮操作、遇到错误或等待您的批准。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:suleymanyaryev/dsh-notification-badge#d7bd5101cfb54751efbad7e336b5931813c30599Notification Badge 以 dsh-notification-badge 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Desktop, browser + webhook notifications and an attention badge on the app icon for DeepSeek Harness on macOS · Linux · Windows: know when your agent finishes a turn, hits an error, or is waiting for your approval — without watching the tab.
Long agent turns are the norm: you kick off a task, switch away, and come back to find the agent
finished five minutes ago — or worse, stuck on an approval prompt the whole time.
dsh-notification-badge listens to the harness's own lifecycle events, pings you the moment your
attention is needed, and keeps a count on the application icon while you are away.
| Event | Trigger | Default |
|---|---|---|
| Agent finished | agent/status flips running → idle, and the turn ran ≥ minTurnDurationMs | on |
| Agent error | agent/error (a step or turn errored) | on |
| Approval needed | approval/request waterfall (observe-only; always delegates with next()) | on |
| Waiting for you | a session's pendingInteraction appears (browser half) | on |
| App-icon badge | either of the above while the window is not focused (desktop shell) | on |
Each event can go to:
osascript (macOS), notify-send (Linux),
PowerShell toast (Windows), optionally with a sound on macOS.Notification API in the Web UI.POST with a Slack-compatible text field, so a Slack incoming webhook
works as-is. Other services need their own field: Discord, for example, ignores text and wants
the same string as content, so point the webhook at a small relay (or a Slack-compatible
bridge) when you need Discord messages.| Channel | Runs on | Best for |
|---|---|---|
Desktop (desktop) | the machine running the dsh server | dsh web on your own machine |
Browser (browser) | the machine viewing the Web UI | a remote server, or any Web UI use |
Badge (badge) | the machine viewing the Web UI, desktop shell only | seeing "3 things need you" at a glance |
Webhook (webhookUrl) | wherever the URL points | phones, Slack, unattended runs |
Browser notifications ask for permission on your first click or keypress, and by default popups
appear only while the window is hidden or unfocused — a window you are looking at already has
your attention (set browserOnlyWhenHidden: false to change that).
The badge counts a session once, while the window is unfocused, and clears the moment you come
back — it means "things you have not looked at yet", not "unread messages". Sessions that stay
short (minTurnDurationMs) are ignored, and subagent sessions never notify or badge.
On the DeepSeek Harness desktop app the server and the page run on the same machine, so both
default-on channels fire for one event: a native osascript/notify-send notification from the
host and a page Notification (which Electron also renders natively). That is two popups per
turn. Keep one:
# ~/.dsh/profiles/desktop/cordis.patch.yml
- id: notify-badge
name: dsh-notification-badge
config:
desktop: false # the page already notifies, and owns the app-icon badge
desktop: true is the right default for dsh web on a remote or headless machine, where the page
is somewhere else.
Do not run this together with
dsh-dock-badge. Both drive the same Badging API and each clears the icon when the page loads, so they overwrite each other's count. This plugin covers everything that one does (and reads pending interactions fromuiSession.sessionStatus, which the session list does not expose), so keep only one of them enabled.
The package is a bundle: dsh plugin add writes the dependency and selects the bundle row.
# Web / headless profiles:
dsh plugin --profile web add dsh-notification-badge
The desktop profile is owned by the application: install it from Settings → Plugins in the
DeepSeek Harness app. dsh plugin --profile desktop add … also works, but only with the app fully
quit and the profile initialized once (dsh refuses to touch an uninitialized desktop profile).
The package ships plain ESM JavaScript — no build step, so a git or registry install needs no
allowBuilds entry. The Web UI picks the client bundle up on the next load.
Add the dependency to ~/.dsh/profiles/<profile>/package.json and list it as a bundle:
"dsh": { "profile": { "bundles": ["…", "dsh-notification-badge"] } }
Override the row in your profile's cordis.patch.yml:
- id: notify-badge
name: dsh-notification-badge
config:
minTurnDurationMs: 10000 # only notify for turns ≥ 10s
webhookUrl: 'https://hooks.slack.com/services/XXX/YYY/ZZZ'
notifyOnApproval: true
desktop: true
browser: true
badge: true
badgeMode: count # count | dot
title: 'DSH'
| Field | Type | Default | Meaning |
|---|---|---|---|
notifyOnIdle | boolean | true | Notify when a turn finishes |
notifyOnError | boolean | true | Notify on agent/error |
notifyOnApproval | boolean | true | Notify when a tool call awaits approval |
minTurnDurationMs | number | 5000 | Skip notifications for quick turns |
desktop | boolean | true | Native desktop notification on the server host |
browser | boolean | true | Browser Notification popups in the Web UI |
browserOnlyWhenHidden | boolean | true | Suppress popups while you are looking at the window |
webhookUrl | string | '' | Optional POST target (Slack-compatible payload) |
title | string | 'DeepSeek Harness' | Title for desktop and browser notifications |
sound | string | 'Glass' | macOS: a system sound name (looked up in ~/Library/Sounds, /Library/Sounds, /System/Library/Sounds) or an audio file path (absolute, or relative to ~/Library/Sounds); '' is silent |
windowsAppId | string | '' | Windows: AppUserModelID the toast is attributed to; empty uses the posting process's registered identity |
badge | boolean | true | Put the attention count on the application icon |
badgeDesktopOnly | boolean | true | Only badge in the desktop shell (a browser tab has no app icon) |
Every field is declared .volatile(), so the values are live: the dsh-settings document
serves them, and a change applies without a reload. webhookUrl is role('secret'), so its value
is stripped before settings cross the wire to the browser.
{
"text": "Agent finished — done in 2m 14s",
"summary": "Agent finished",
"body": "done in 2m 14s",
"level": "info",
"ts": "2026-08-21T12:34:56.000Z"
}
The Dock tile belongs to the Electron browser process, so a host-side plugin can never touch it.
The renderer does not need to: Electron implements the standard Badging API in the browser
process, so navigator.setAppBadge(n) from the page reaches the same code path as
app.setBadgeCount() — no shell patch, no IPC channel, no preload hook. The API is
[SecureContext], and the desktop shell serves the UI from dsh-app:// (registered secure: true).
Three sharp edges, all handled:
setAppBadge(0). Chromium treats a numeric zero as a protocol violation and
Electron answers with ReportBadMessage, which terminates the renderer. Clearing always goes
through clearAppBadge().99+, so badgeMaxCount above 99 changes nothing.NotAllowedError when the document may not badge; the plugin swallows
that and retries on the next change.A browser tab gets no badge by default (badgeDesktopOnly: true): Chrome and Edge only badge
installed PWAs, so outside the desktop shell the call is inert at best.
If nothing appears in the Dock, check System Settings → Notifications → DeepSeek Harness → "Badge application icon" — an app that was never granted notification permission has its badge ignored by the system. To test the plumbing directly, from the app window's console:
navigator.setAppBadge(7); // badge shows "7"
navigator.clearAppBadge(); // badge disappears
ctx is an effect. Cordis registers each listener through the
plugin fiber, so they are removed automatically on unload/hot-reload; there is no manual cleanup
path.approval/request is a waterfall. This plugin only observes it, so its listener always calls
next() — returning without it would claim the decision (and resolve as unavailable), swallowing
the real answerers.{ name: id } and no config, so apply on the client receives no
row config; the host half declares the options .volatile() and the client reads them back through
ctx.configForms.get('notify-badge') — the same path official client plugins use. The entry id in
cordis.patch.yml is that namespace, so if you rename the row, update ENTRY_ID in client.js.uiSession.sessionStatus. sessions.list rows carry running but
not pendingInteraction; the status projection is the client's own view of
{ running, pendingInteraction, completionUnread }, and a pendingInteraction is an object whose
kind is approval, question, or plan-review.agent/error and then flips the
status to idle. The error is recorded before the notifyOnError gate, so the idle flip stays quiet
whether error notifications are on (the error was already announced) or off (nothing is posted at
all) — a failed turn is never reported as "Agent finished".origin: "subagent" never notify or badge.
The host half learns that from session/created; the browser half can only read origin from the
session list, so a session the list has not delivered yet stays untracked until it can be
classified (and is adopted then, so an already-waiting session still badges).ENTRY_ID disagree, the
client logs one warning instead of silently running on defaults.Verified against DeepSeek Harness 0.2.1-rc.2, and engines.dsh declares ^0.2.1-rc.2. The
installer refuses dsh plugin add for a package whose range does not match the running harness
(unless that exact package@version is version-exempted with dsh plugin allow-version); a bundle
that is already listed in a profile is only warned about, so the declared range is an install gate
rather than a load gate. client.js is hand-written in the shape the client module system expects,
so no build step and no source map are needed.
From a checkout of this package:
npm install # @deepseek-ai/schemastery, for the Config schema
npm test # syntax check + host and browser-half tests
To run it inside a harness source checkout, point a patch file at this directory and start the Web UI:
# dev.patch.yml (keep it out of version control)
- insert:
- id: notify-badge
name: dsh-notification-badge
config:
minTurnDurationMs: 0
pnpm dsh web --patch ./path/to/dev.patch.yml
Edits to index.js hot-reload without a restart; a rebuilt client.js is picked up on the next
page load.
MIT © 2026 Suleyman Yaryev suleymanyaryev@gmail.com. The notification half is derived from dsh-notification
by Nishit Patel, and the icon badge from dsh-dock-badge; both were MIT-licensed, and the original
copyright notice is retained in LICENSE.
badgeMode | count | dot | count | Number of sessions, or an unnumbered dot |
badgeMaxCount | number | 99 | Highest number rendered |
badgeOnIdle | boolean | true | Count a finished turn |
badgeOnApproval | boolean | true | Count a session waiting on you (including one already waiting at load) |
badgeClearOnFocus | boolean | true | Clear the badge when the window is focused or visible again |
index.js is required even on a machine where only the browser half does anything.