dsh-notification

dsh plugin --profile web add 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