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