dsh-task-reminder
Conversation task-completion reminders for the DeepSeek Harness Web UI
[](LICENSE)
[](https://github.com/deepseek-ai)
[](https://github.com/hawkongz/dsh-task-reminder/stargazers)
Language: English | ็ฎไฝไธญๆ
---
## ๐ Table of Contents
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Usage](#-usage)
- [Troubleshooting](#-troubleshooting)
- [Topics](#-topics)
- [Contributing](#-contributing)
- [License](#-license)
---
Agent turns in DeepSeek Harness keep running while you read the news in another
window โ and the only signal that a task finished was the session list turning
idle. This plugin turns that moment into a real reminder, without leaving the
browser surface you already use.
When a conversation task stops, the plugin sends a **Windows system
toast** (Web Notification โ the native notification in the bottom-right corner
of your OS, visible while the browser is in the background; click it to return
to that session) and plays a synthesized chime. Three stop reasons are
covered: **task complete**, **the agent is waiting for your answer**
(`ask_user_question` pending), and **an error stop** (any failed turn โ a
gateway HTTP error such as 400 / 401 / 429 / 500 / 502, a provider outage, or
a connection failure) โ one stop is reported once, with the error taking
precedence. The toast
timing has two modes: **Always** (every completion, no matter whether the
browser window is in the foreground) or **Only when unfocused** (when you
switch the tab away or the browser window loses focus). There is no in-app
card: the OS toast is the only visual channel. Everything is configured on its
own settings page and persists across restarts.
The whole plugin lives on the browser side. The host half (`index.js`) is an
empty `apply() {}`, and there are no runtime dependencies โ the host ships it
to the page as a client plugin.
## โจ Features
* **Windows system toast as the single visual channel:** Web Notification API,
an OS toast you can see while the app is in the background. Clicking it
brings the window forward and opens the session. Three stop reasons are
covered: **task complete**, **waiting for your answer** (the agent blocked
in `ask_user_question` / plan review โ detected by reading the read-only
`uiSession.sessionStatus` snapshot, never by joining the question waterfall),
and **error stop** (`api-session/error` โ any failed turn: a gateway HTTP
error such as 400 / 401 / 429 / 500 / 502, a provider outage, or a
transport failure). One stop is
reported once, error first: when a stop arrives, the plugin classifies it
from the session's durable log (the `turn/end` reason) โ a completed turn
(or one that hit its output ceiling) reports completion, a failed turn
reports the error with the gateway's own message and never a completion
toast, and a cancelled turn reports nothing. The classification read also
takes the last `turn/start`: while the newest turn is still open (that
`turn/end` belongs to the previous turn), the plugin retries until it
lands โ pressing Stop is never misreported as a completion. The chime and
the toast go out together in the same pass. If classification is
unavailable, the completion toast goes out at once and a same-stop error
arriving within 5 s retracts it โ error first, one reminder per stop. A
repeated edge while classification is in flight (a stale list replay) is
held back by the in-flight guard and the completionโcompletion dedupe.
Two timing modes โ **Always** (every stop) or **Only when unfocused**
(tab switched away or window unfocused) โ pick one on the settings page. The
browser asks for notification permission once on the first load โ the
Notification API has no permission-free path, which is why in-page-only
plugins never show such a prompt. If the permission was reset afterwards, a
**Request notification permission** button under the System toast row
re-asks. A denied or unsupported Notification API degrades to a clear hint
on the settings page instead of failing silently.
* **Four synthesized chimes:** two-tone (classic), rising three-tone, rising
arpeggio, and soft triangle โ generated live with Web Audio, so no audio
files are shipped. Picking an effect plays it immediately at the current
volume; there is no separate preview button. The chime sounds on every stop,
whatever the toast timing mode.
* **Dedicated settings page:** `Settings โ Task reminder` (no more rows in
`Settings โ General`), with one-click restore defaults.
* **Three-channel completion detection with deduplication:** the host-forwarded
`api-session/status` event, the official session list's own `running` bit, and
the `running` bit inside the `uiSession.sessionStatus` snapshot (the same
source as the sidebar's running light โ the reliable path when a forked
session's list projection is stale) share one edge table, so one completion
never fires twice; a repeated edge while classification is in flight is
additionally held back by the in-flight guard and the completionโcompletion
dedupe.
* **All values persist in browser local storage** and survive restarts, so the
host half needs no settings namespace.
## ๐ Quick Start
> **What you need:** DeepSeek Harness running with the `web` profile
> (`dsh web`), pnpm on your `PATH` (the `dsh plugin` command forwards to it),
> and a browser you can hard-refresh.
**Step 1 โ Open a terminal**
* macOS / Linux: open Terminal.
* Windows: `Win + R`, type `powershell`, press Enter.
**Step 2 โ Install and register with one command**
`dsh plugin` installs the package into the profile directory and appends the
bundle to the profile's `dsh.profile.bundles` in a single step โ no manual
registration:
```powershell
# Windows (PowerShell) โ run it from any directory
dsh plugin --profile web add @hawkongz/dsh-task-reminder
```
```bash
# macOS / Linux
dsh plugin --profile web add @hawkongz/dsh-task-reminder
```
This installs the published package from the npm registry โ the same way every
other DSH plugin is installed. (The unscoped name
`dsh-task-reminder` is permanently unavailable: npm rejects it as too similar
to the existing package `dsh-taskreminder`, so the scoped name is the only
registry form.)
To install from the GitHub repository instead โ the default branch, or a
pinned release tag โ use the `github:` spec:
```powershell
# default branch
dsh plugin --profile web add github:hawkongz/dsh-task-reminder
# pin a release instead of the default branch: append the tag
dsh plugin --profile web add github:hawkongz/dsh-task-reminder#