# dsh-notification

> 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.

## Metadata

- Author: [@omdsh-dev](https://github.com/omdsh-dev)
- Repo: <https://github.com/omdsh-dev/dsh-notification.git>
- GitHub: [omdsh-dev/dsh-notification](https://github.com/omdsh-dev/dsh-notification)
- Stars: 69
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `dsh`, `dsh-plugin`
- Forks: 8
- Open Issues: 0
- Last push: 2026-08-19T07:12:27.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:omdsh-dev/dsh-notification
```

## Wiki

## 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 `notification` session projection (pure fold over logs), client listens to session list completion edges, browser `Notification` API 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

```bash
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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-notification](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-notification)
Wiki generated by AI (model: `MiniMax-M2.5`)