DSH Web desktop notification plugin that sends browser system notifications when tasks complete, encounter errors, or wait for user interaction. Supports status-based toggling and keyword filtering.
Install
$ dsh plugin --profile web add github:omdsh-dev/dsh-notificationRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
One-Line Description
Adds desktop notification capability to DeepSeek Harness web client. When a session completes a turn, encounters an error, or needs your approval, answer, or plan review, the browser will pop up a system notification so you can stay informed even when switching to other tabs.
Core Features
- Pop desktop notifications when tasks complete or error, with individual toggles for five end states (completed, errored, aborted, blocked, token limit reached)
- Separate notifications for user interactions, covering approval, question, and plan review waiting scenarios
- Filter notifications using include/exclude keyword rules, supporting literal matching or regex with optional case sensitivity
- Provides a "Settings > Notifications" panel for one-click browser permission request and test notification
- Preferences stored in browser localStorage, persisting across refreshes; smooth migration from v2 → v4
- Only notify when task is not in view (still alerts when page is backgrounded or viewing other sessions); new notifications replace old ones for the same session
Technical Implementation
- Language: TypeScript (strict ESM host package, CJS single file client bundle, React 18 JSX)
- Key Dependencies: @deepseek-ai/cordis, @deepseek-ai/dsh-session-projection, @deepseek-ai/dsh-session, zod
- Architecture Pattern: Host registers a
notificationsession projection (pure fold over logs), client listens to session list completion edges, browserNotificationAPI pops notifications; no harness modification, relies on existing client composition in profile - Entry Files:
src/index.ts(host),src/client/index.ts(browser),src/invariant.ts(diagnostic companion)
Use Cases
After starting a long-running task, you switch to other tabs or workspaces; when DSH completes, errors, or waits for your confirmation, you want to be pulled back by a system notification; and you only care about some tasks (e.g., only care about completions with "deploy" keyword, or only want to mute certain tool calls), with other tasks completing quietly.
Prerequisites & Compatibility
| Dependency | Min Version | Notes |
|---|---|---|
| DSH | Not declared | Resolved via link:../dsh; host uses Cordis + session projection channel, no additional feature flag needed |
| Node.js | >= 22 | Build target node22 (see build.mjs) |
| Platform | Cross-platform | Web GUI client plugin only, depends on browser Notification API |
| Native modules | None | No native dependencies introduced |
| React | ^18.2.0 | React used in client settings section, peerDependency |
Installation
dsh plugin --profile web add github:omdsh-dev/dsh-notification
Configuration
Host side (written under config in cordis.yml plugin line):
| Config | Type | Description | Default |
|---|---|---|---|
maxBodyChars | Number (≥1) | Character budget for reply body in projection; excess truncated on host side with ellipsis | 400 |
Client side (modified in Settings > Notifications panel, stored in localStorage):
| Config | Type | Description | Default |
|---|---|---|---|
| Master toggle (enable notifications) | Boolean | Stop all notifications when off, preferences preserved | On |
| Notify on completion | Boolean | Notify when task completes normally | On |
| Notify on error | Boolean | Notify when task errors | On |
| Notify on abort | Boolean | Notify when task is aborted | Off |
| Notify on block | Boolean | Notify when task is blocked | Off |
| Notify on token limit | Boolean | Notify when token limit reached | Off |
| Notify on pending approval | Boolean | Notify when DSH awaits your approval | On |
| Notify on pending answer | Boolean | Notify when DSH asks a question | On |
| Notify on pending plan review | Boolean | Notify when DSH awaits your plan review | Off |
| Keyword rules | List | Include/exclude rules, supporting literal or regex; include rules require at least one match to notify, exclude rules suppress on match | None |
| Require manual dismiss | Boolean | Notification stays visible until manually dismissed | Off |
| Notify only when task not in view | Boolean | Don't pop notification when current session is being viewed; still pops when switching to other sessions, workspaces, or page hidden | On |
FAQ
Q: Does installation require harness modifications?
A: No. Host auto-mounts via session projection, client relies on session list, settings shell, and locale already included in default web profile, no harness config changes needed.
Q: Can notification permissions be restored after denial?
A: Not from within the page. After denial, you must manually re-enable Notification permissions in browser site settings, then return to settings panel and click "Request Notification Permission".
Q: Will turns completed offline send notification after reconnection?
A: No. On reconnection, baseline is refetched; completion edges during offline period won't trigger notifications.
Q: Does clicking notification open to specific turn?
A: No. Click only focuses window, no deep link to specific turn.
Q: Do background sub-sessions notify?
A: No. Plugin skips sessions with origin subagent.
Q: What content do keyword rules match?
A: Matches session title, current turn reply text, and tool names called in current turn (deduplicated by appearance order), not earlier turns.
Q: Does it affect model calls?
A: No impact. No new tools added, no prompt modifications; reply body only truncated on host side per maxBodyChars.
Getting Started Difficulty
Beginner — after installation, authorize in "Settings > Notifications"; for fine-grained control, add keyword rules; no internal concepts required.
Known Issues & Limitations
- Notifications require page to be open (no pop after tab closed); site permission denied cannot be restored from within page
- Completions during offline won't send notification after reconnection
- Keyword rules only match session title, latest turn reply text, and tool names, not earlier turns
- Notification body is plain text summary; click only focuses window, no deep link to specific turn
- Host side reply body truncated to
maxBodyChars(default 400 characters), excess shown as ellipsis - Notification tag for same session includes turn number; new notification replaces previous one for that session
Desktop notifications for the DeepSeek Harness web GUI. When a session finishes a turn, the browser shows a system notification (via the Notification API), so you can switch tabs and still know when DSH is done. Per-outcome toggles and include/exclude keyword rules control exactly which completions notify.
No harness change is needed: the host contributes a session projection (a bounded summary of each session's last completed turn), and the client watches the session list's completion reminder and applies its own persisted preferences.
host: notification projection (last turn's reason/text/tools) --session/projection--> browser
client: session list completion reminder (live, dedup) + persisted settings
-> permission + current-session visibility gate
-> new Notification("DSH finished", { body: "deploy done" })
Install
dsh plugin --profile web add https://github.com/omdsh-dev/dsh-notification/archive/refs/tags/v0.1.2.tar.gz
Restart the web server so the host half and the served client bundle pick up the plugin. The default dsh web profile has the required client composition (the session list, the settings shell, and locale).
The settings section lives under Settings > Notifications.
Settings
| Setting | Default | Effect |
|---|---|---|
| Enable notifications | on | Master switch; off stops every notification while keeping rules. |
| Notify on completed / error / aborted / blocked / token limit | completed + error on, rest off | Which turn-end reasons notify (the host projection reports the reason). |
| Keyword rules | none | Include/exclude filters matched against the session title, the turn's reply text, and its tool names. Include rules: at least one must match. Exclude rules: a match suppresses. Rules support literal or regex matching with an optional case-sensitive flag. |
| Require manual dismiss | off | The notification stays until dismissed. |
| Only notify when the task is out of view | on | Suppress a notification only when its session is currently in view. A completion still notifies while the page is hidden or while another session/workspace is open. Turn it off to notify even for the session being watched. Notifications for the same session replace each other. |
Preferences persist in the browser (localStorage). The section also grants browser permission and sends a test notification.
Configuration
Host-side tunables live on the plugin row in cordis.yml:
- id: dsh-notification
name: dsh-notification
config:
maxBodyChars: 400 # projection body budget; longer replies are ellipsized host-side
Model experience
| Aspect | Effect |
|---|---|
| Token cost | None — notifications are UI-only and never enter a request. |
| Tool calls | None — the model gets no new tool. |
| Session log | Unchanged — the projection reads the existing log and adds no events. |
| Prompt | Unchanged — no system-prompt section is registered. |
Permission boundary
- The host folds a pure projection over the session log (turn reason, bounded reply text, tool names) and the projection seam delivers it to the browser; the plugin writes nothing to the log and registers no model-facing tools.
- The client watches the session list's completion reminder (a live "finished while not selected" edge the runtime already computes) and shows a notification only when the user has granted Notification permission.
- Rule matching runs client-side against the projected content; the reply body never exceeds
maxBodyChars.
Development
pnpm install # links the sibling dsh checkout for build and tests
pnpm run check # typecheck + tests + build
pnpm run test # vitest (host projection + composition, client decision/runner/helpers/section)
pnpm run build # esbuild host/client/invariant bundles + tsc declarations
The repo expects the harness checkout at ../dsh for the dev-time link: resolutions. The composition spec boots the real SessionStore and SessionProjectionRegistry and proves the fold.
Known limitations
- Notifications require the page to be open (the browser shows them while it is hidden, but not after the tab is closed) and Notification permission granted; a denied site permission cannot be overridden from inside the page.
- Notifications fire once per finished turn (a running→idle edge on any session); a completion that happened while the page was disconnected is not re-notified on reconnect.
- The rule subject is the session title plus the last turn's reply text and tool names — earlier turns are not matched.
- Notification body is a flat text snippet; the click action only focuses the window (no deep link to the turn).
License
MIT