dsh-notification

dsh-notification

Desktop, browser + webhook notifications 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 listens to the harness's own lifecycle events and pings you the moment your attention is needed.

What it does

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

Each event can go to:

• Desktop notification — zero dependencies: osascript (macOS), notify-send (Linux), PowerShell toast (Windows).
• Webhook — a JSON POST with a Slack-compatible text field, so a Slack/Discord/generic incoming-webhook URL works out of the box.

Install

dsh plugin --profile web add dsh-notification
# or straight from git:
dsh plugin --profile web add github:nishit130/dsh-notification

The package ships plain ESM JavaScript — no build step, so a git install needs no allowBuilds entry.

Where notifications appear

Three channels, three places:

Channel	Fires 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
Webhook (webhookUrl)	wherever the URL points	phones, Slack, unattended runs

Browser notifications use the standard Notification API: the Web UI asks for permission on your first click or keypress, and by default popups appear only while the tab is hidden — a visible tab already has your attention (set browserOnlyWhenHidden: false to change that).

Running everything on one machine with the tab hidden? You'd get both a desktop and a browser popup for the same event — turn one channel off (desktop: false or browser: false) if the pair bothers you.

Configuration

Override the row in your profile's cordis.patch.yml (or via the Settings UI):

- insert:
    - id: notify
      name: dsh-notification
      config:
        minTurnDurationMs: 10000        # only notify for turns ≥ 10s
        webhookUrl: 'https://hooks.slack.com/services/XXX/YYY/ZZZ'
        notifyOnApproval: true
        desktop: true
        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 browser popups while the tab is visible
webhookUrl	string	''	Optional POST target (Slack-compatible payload)
title	string	'DeepSeek Harness'	Desktop notification title

Webhook payload

{
  "text": "Agent finished — done in 2m 14s",
  "summary": "Agent finished",
  "body": "done in 2m 14s",
  "level": "info",
  "ts": "2026-08-21T12:34:56.000Z"
}

Design notes

• Everything registered through ctx is an effect — the listeners are removed automatically on unload/hot-reload; there is no manual cleanup path (Cordis revertible effects).
• approval/request is a waterfall. This plugin only observes it, so its listener always calls next() — returning without it would claim the decision and swallow the real answerers.
• Never break the loop. Desktop spawns are detached and fire-and-forget; webhook failures are swallowed. A notifier must never surface an error into the agent's turn.

Local development

Copy dev.patch.example.yml to dev.patch.yml (gitignored), point it at your checkout's absolute path, then from a harness source checkout:

pnpm dsh web --patch ./path/to/dsh-notification/dev.patch.yml

Edits to index.js hot-reload without a restart. Run the tests with npm test.

License

MIT