Introduction

DeepSeek Harness (DSH) is a plugin-based agent development framework. Running DSH typically relies on the dsh web service, which means an agent’s task status, approval requests, and scheduled trigger events are mainly displayed in the browser page.

When an agent executes tasks in the background or requires your approval, these key details can easily be missed if you look away from the page. The dsh-desktop-notify plugin bridges key DSH events directly to OS desktop notifications, ensuring you do not miss important status changes.

Features

This plugin is automatically loaded with dsh web and supports Windows and Linux. Core capabilities include:

  • Task status monitoring: Notify task completion when an agent transitions from running to idle.
  • Interaction pending reminder: Remind you to return to the page and provide input when an agent asks a question using tools such as ask_user_question.
  • Approval and rejection notifications: Emit an explicit notification when an operation is silently denied because the approval policy is never.
  • Background task tracking: Remind individually when background subagents, goals, or command tasks finish.
  • Scheduled task triggering: Notify only when a scheduled task is actually delivered (triggered), not just when created.
  • Startup and mount broadcast: After each dsh web startup, push the plugin mount status (normal / degraded).
  • Click-through support: Supports clicking a notification to jump back to the corresponding session, built-in page, or external URL.
  • Dual-channel notifications: Prefer Web Notifications (click precisely activates the tab), and automatically fall back to native Toasts when permission is unavailable or cannot be obtained (Windows uses koffi, Linux uses D-Bus).
  • Immediate permission change feedback: Immediately notify the current operating mode when browser notification permission changes.

Installation and Enablement

Prerequisites

  1. DSH version: Must satisfy >= 0.1.7-rc.2 and <= 0.2.0-rc.2.
  2. Web startup: Must have started dsh web at least once (web profile must already be generated).
  3. Runtime environment: Windows requires koffi (the plugin handles this automatically); Linux has no additional dependencies.

Installation steps

On DSH’s Plugin Management page, choose Add Plugin and enter one of the following as the installation target:

  • Package name: @mvyvn/dsh-desktop-notify
  • Repository URL: https://github.com/Mvyvn/dsh-desktop-notify

After installation, fully restart the dsh web process and refresh the DSH page.

Initial authorization

If you want to use the Web Notification channel, browsers require a user gesture to trigger the authorization dialog. The plugin displays a centered card on the DSH page; click the “Settings” button to grant authorization. After authorization, notifications are displayed directly by the browser; if denied or not authorized, the plugin automatically falls back to native Toast mode.

Usage

The plugin registers a Cordis service named desktopNotify. Other plugins can call it via ctx.get('desktopNotify').

Basic push

Use the push method to send a notification. By default, it follows the “focus gating” rule (meaning it will not disturb you when you are already viewing that session).

// 在你的插件代码中
const desktopNotify = ctx.get('desktopNotify');
if (!desktopNotify) return;

// 普通推送，受聚焦门控影响
desktopNotify.push({
  title: '构建完成',
  message: '工作区/会话:全部通过',
  urgency: 'normal', // 'low' | 'normal' | 'critical'
  sessionId: agent.session
});

Forced push

Use pushAlways to bypass all gating and force a popup.

desktopNotify.pushAlways({
  title: '磁盘告急',
  message: '剩余 1GB',
  urgency: 'critical'
});

Result query

Use the notify method to get detailed push results (whether queued, whether silenced, etc.).

const result = desktopNotify.notify({
  title: '构建完成',
  sessionId: agent.session
});
// 返回: { ok: true, queued: false, silenced: true, reason: 'silenced', ... }

Click-through configuration

Configure click behavior via the click field. If click is omitted, the notification is not clickable.

// 跳转回指定会话
desktopNotify.push({
  title: '打开文档',
  click: {
    type: 'session',
    sessionId: agent.session
  }
});

// 跳转外部 URL
desktopNotify.push({
  title: '查看详情',
  click: {
    type: 'url',
    url: 'https://example.com'
  }
});

Silent mode configuration

On the plugin settings page, you can configure silent modes (session / tab / never) for different notification types to determine when not to send notifications.

Notes

  • Version compatibility: The plugin depends on DSH services such as connection and webServer, with a strict version range. Behavior outside the version range is not guaranteed to be compatible.
  • License: The plugin is licensed under GPL-3.0-or-later. Please confirm source code compliance before installing.
  • Permission limitation: Browser notification permission must be triggered by a user action on the page; automatic popups are not allowed.
  • Icon: Native Toasts use the DSH logo (transparent PNG/ICO) and automatically adapt to light/dark mode based on the system theme.

Summary

dsh-desktop-notify provides DSH with system-level monitoring capabilities, translating complex agent background states into intuitive desktop reminders. Through the desktopNotify service interface it provides, developers can easily integrate notifications and enhance the user experience.