Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture that allows functional extensions. When an Agent runs sessions or handles tasks in the background, developers may not be able to monitor session state changes in time. The dsh-notify-xc plugin uses the browser Notification API to show system-level notifications when a task completes, a runtime error occurs, or human intervention is required, addressing the issue of missed status updates.

What Is This

This is a browser-side plugin maintained by xchannel1987. It is a compatibility-focused rewrite based on dsh-agent-notify and is adapted for DSH 0.1.2-alpha.4. The plugin runs purely in the browser (with an empty host half), requires no build steps, and is licensed under MIT.

Core Features

Task Completion Notification

Triggered when a session transitions from running to stopped. The notification includes the session title and a summary of the last reply. The plugin applies a strict completion check: if the session delegates a task to a subagent (workflow, Ralph, or background job) and “yields the turn,” it is not treated as completed; it waits for all background tasks to finish before deciding. Persistent background shell tasks (such as a dev server) are not considered in this check.

Runtime Error Notification

When a session ends with a session-level error (lastAgentError), an error notification is shown. The notification summary displays the error information, such as a 429 rate-limit error or an authentication failure. Task completion and runtime error notifications are mutually exclusive; only one type is sent per turn.

Input Request Notification

When the Agent is waiting for user action (question, approval, or plan-review), a reminder is shown immediately. A “persistent mode” setting is supported, where the notification will not automatically dismiss until the user handles it.

Click to Open Session

Clicking the system notification bubble makes the browser automatically focus the DSH page and open the corresponding session, enabling quick responses.

Workspace Ownership in Notifications

When enabled, notification titles include a [workspace name] prefix, which helps quickly locate the source while running multiple projects concurrently.

Configurable Notification Types

The three notification categories—task completion, input request, and runtime error—have independent switches and do not affect each other. Settings include “include subagent notifications,” “do not notify while waiting for subagents,” and “persistent input request notifications.”

False-Positive Prevention Design

The plugin prevents false positives using a baseline mechanism, deduplication logic, and a grace-period recheck of 1.2 seconds. The first snapshot after page load or reconnection is used as the baseline, so historical events are not replayed. If a session is woken by a background result within the grace period, the completion notification is canceled. For troubleshooting, use the console command window.__dshNotifyXc.probe('<sessionId>') to inspect session status.

One-Click Notification Clearance

When more than 3 notifications are present, a floating “Clear Notifications” button with a count badge appears in the top-right area of the page. Clicking it dismisses all notifications sent by this plugin within the current session.

Installation and Enablement

Install using the DSH CLI:

dsh plugin --profile web add dsh-notify-xc

After installation, restart DSH and refresh the browser page to enable it.

Typical Usage

  1. Open DSH settings and go to the “Task Notifications” section.
  2. Check the notification type switches (all are enabled by default), and confirm that the system notification permission shows “Granted.”
  3. Click the “Test” button to verify that the notification flow is working.
  4. During actual use, when the Agent completes a task, encounters an error, or needs your approval, the browser notification center will automatically display a notification bubble.

Notes

  • Platform Compatibility: This feature depends on the browser Notification API and currently supports desktop Edge and Chrome. If a mobile browser does not support system notifications, the settings page will automatically become disabled and show a prompt.
  • iOS Limitation: iOS system notifications only support Service Worker Web Push. This plugin does not integrate with that mechanism, so iOS is not supported.
  • Permission Request: The first click on the page will automatically request notification permission.
  • Cleanup Limitation: Clicking the notification clear button only dismisses live system notifications that are still referenced within the current session. Historical notification bubbles left in the notification center after a page refresh cannot be reclaimed by the script and must be cleared manually.

Summary

dsh-notify-xc provides DSH with standardized system-level notification capabilities, helping developers stay informed about the Agent’s runtime status. Through false-positive prevention and flexible configuration, it improves development efficiency while maintaining notification accuracy.