Introduction

DeepSeek Harness (DSH) uses a plugin architecture that allows developers to extend functionality. During long sessions or background tasks, you may miss important events. dsh-notify is a plugin bundle that sends desktop notifications and plays a sound when a session completes a task, asks a question, or requires approval while you are not in the current session.

Features

The plugin mainly provides the following capabilities:

  1. Trigger timing: It can trigger notifications on the following events:
    • A conversation turn ends (turn/end)
    • A persistent goal completes (goal/change)
    • An agent calls the question API (tool/call)
    • An action requires user approval (approval/asked)
  2. Subagent filtering: It only listens to top-level sessions. The plugin uses the origin: 'subagent' marker in the session header to filter out all subagent events and avoid noise from intermediate processes.
  3. Presence detection: It notifies only when the user is away.
    • If the page is the current tab and the window has focus, the user is considered “in session,” and no notification is shown.
    • Switching tabs, minimizing, or closing the page is considered “away,” which triggers a notification.
    • If the tab crashes or disconnects for more than 45 seconds (TTL), it is automatically treated as away.
  4. System default sound: It attempts to call canberra-gtk-play -i message or pw-play/paplay to play a system sound. This can be disabled via configuration.
  5. Notification backend: It supports Linux notify-send (auto-detection), plain console output, or any custom command (with template replacement).

Installation

This package is a DSH-specification bundle, containing a host plugin and a browser client half.

Install from a local directory

# 1. 构建（如果尚未构建）
npm install
npm run build

# 2. 安装到指定 profile
dsh plugin --profile web add /path/to/DSH_remind

dsh plugin automatically detects dsh.bundle.patch and appends it to the profile’s bundle list. Restart the profile to apply the changes.

Install from GitHub

dsh plugin --profile web add github:you/dsh-notify#<commit-sha>

Verify the configuration layer

Check whether the configuration loads correctly without starting the system:

dsh --profile web --patch /path/to/DSH_remind/cordis.patch.yml --dump-config

Configuration

It runs with zero configuration by default. In the profile’s cordis.patch.yml, override that line by id.

Default configuration parameters

Field Type Default Description
backend auto \| notify-send \| console \| command auto Auto-detect notify-send; fall back to console otherwise
command string '' Custom command template executed via /bin/sh -c, supporting {title} and {message} placeholders
urgency low \| normal \| critical normal Urgency for notify-send
onTurnComplete boolean true Notify when a turn answer completes
onGoalComplete boolean true Notify when a goal completes
onUserQuestion boolean true Notify when the agent asks a question
onApproval boolean true Notify when approval is required
onlyWhenAway boolean true Notify only when away
playSound boolean true Play the system sound
debounceMs number 0 Minimum interval for the same type of notification (milliseconds)

Custom command examples

Customize notification behavior in the command backend:

# 通知 + 自定义提示音文件
config:
  backend: command
  command: 'notify-send --app-name "DeepSeek Harness" --urgency critical "{title}" "{message}" && paplay "$HOME/.local/share/sounds/custom.oga"'

# 通知 + 留痕到日志文件
config:
  backend: command
  command: 'notify-send "{title}" "{message}"; echo "$(date "+%F %T") {title} | {message}" >> "$HOME/.local/share/dsh-notify.log"'

How It Works

The plugin is split into a browser side (client half) and a host side (bundle entry):

  • Browser side: It listens for page visibility changes (visibilitychange), focus/blur (focus/blur), and heartbeat (15s). It reports the current session ID and presence state to the host via RPC.
  • Host side: It subscribes to the session/event stream. Before processing an event, it first checks whether the session is top-level (excluding subagent), then checks whether the user is “present” according to the presence service.
  • Execution: Through debouncing, it finally triggers notification and sound playback. Notification failures do not affect the session itself.

In Headless or TUI environments, because there is no browser-side reporting, presence is always “away,” and all events trigger notifications.

Notes

  1. Pure event observer: The plugin does not intercept or modify session behavior. Notification failures do not affect DSH’s operation.
  2. Permissions and security: Please review the source code and license before installation. The plugin runs with the permissions of the current DSH process. Be aware of security risks with custom commands.
  3. Headless scenarios: In environments without a browser, all events trigger notifications.