In DeepSeek Harness (dsh) headless or background mode, task status (completion, error, blocked, etc.) is often known only to the process itself, making it difficult for developers to promptly learn the agent’s execution result or any blockers. dsh-notify is a monitoring and notification plugin that proactively pushes task status to configured channels, solving the visibility problem of background tasks.

This is a task monitoring and notification plugin designed for DeepSeek Harness (dsh), maintained by ikashana. It listens to task lifecycle events and notifies users under specific conditions via HTTP webhooks, A2A agents, MCP tools, or local Windows speech. The plugin is implemented in pure Node.js, requires zero runtime dependencies, and needs no build step. It is installed using dsh’s bundle patch mechanism.

Core Features

dsh-notify provides four main trigger mechanisms and four delivery channels:

  • turn/end alerting: Monitors task states such as completion, error, blocked, and token limit exceeded. By default, it only listens and does not send notifications. It supports configuring a whitelist of reason.kind values to monitor, for example, excluding the user-initiated aborted state. In multi-turn jobs, if a new turn begins within the cooldown window (default 10 seconds), the previous turn’s notification is canceled and only the final status is reported.
  • Human confirmation and timeout escalation: Sends a notification when a dialog requiring human confirmation or an ask_user_question tool call is triggered. If no confirmation result is received within 10 minutes, an escalated alert is sent through SAPI speech and priority channels.
  • SAPI speech notifications: Supported only on the Windows platform, it invokes system text-to-speech to read notifications aloud. It uses PowerShell’s -EncodedCommand to transmit UTF-16LE Base64, avoiding garbled Chinese text. It plays independently in the background without a console window.
  • Multi-channel support:
    • HTTP: Supports services such as QQ bot, ServerChan, DingTalk, WeCom, and ntfy, with template rendering and retry on failure.
    • A2A: Sends unidirectional JSON-RPC 2.0 messages to A2A protocol agents and supports UUID deduplication.
    • MCP: Acts as a streaming HTTP notification bridge and supports protocol version handshake.
  • Zero dependencies, no build step: Implemented in pure Node.js, with no additional runtime dependencies, and installed through dsh’s bundle patch mechanism.
  • Model-initiated notification tool: Provides a notify tool (disabled by default), allowing the model to proactively push messages to users during execution.

Installation and Enablement

By default, the plugin operates in “listen only, no sending” mode (no HTTP/A2A/MCP channels, speech disabled, tools disabled). After installation, channels must be explicitly enabled in the configuration.

Installation Command

dsh plugin --profile web add github:ikashana/dsh-notify

It also applies to headless mode, and speech as well as HTTP/A2A/MCP channels can still be delivered normally.

Configuration

The plugin is inserted through a bundle patch, and the configuration file is cordis.patch.yml. Because it replaces the entire configuration object, reserved keys must be rewritten.

- id: notify
  config:
    http:
      channels:
        - id: ntfy
          url: 'https://ntfy.sh/my-topic'
    sapi:
      enabled: true
    tools:
      notify:
        enabled: true

Configuration supports template variables ({{title}}, {{reason}}, {{text}}, {{duration}}, {{timestamp}}). Private configuration (URLs containing secrets) should be placed in local files and ignored with gitignore; the repository contains no hardcoded secrets.

Typical Usage

  • Configure HTTP channels: Use the HTTP template rendering feature, which supports environment variables (${env:XXX}) and credentials (${credential:REF}).
  • Enable SAPI speech: Turn on speech notifications in a Windows environment.
  • Model-initiated notification: Set tools.notify.enabled: true in the configuration, allowing the model to call the notify tool to push messages.
  • Confirmation result reporting: Set notifyDecided: true to send results such as “confirmed” or “rejected” after human confirmation ends.
  • Multi-turn jobs: By default, if a new turn begins within the cooldown window (default 10 seconds), the previous turn’s notification is canceled and only the final status is reported.

Use Cases and Notes

  • Use cases: Developers who need long-running background tasks and want real-time awareness of task success, failure, or blockage; scenarios that require alerts through speech or specific Webhook channels.
  • Notes:
    • The plugin runs with the permissions of the current dsh process. Review the source code and license (MIT) before installation.
    • Model-initiated notify messages bypass the turnEnd.includeText privacy switch and appear in notifications as raw text. It is disabled by default for security.
    • It depends on @deepseek-ai/schemastery.
    • SAPI speech is supported only on Windows.
    • Multi-turn jobs report only the final status by default; if intermediate status is required, adjust the cooldown window or configuration.

dsh-notify provides a complete solution covering status monitoring, human confirmation, and multi-channel delivery. It is silent by default and becomes active only after configuration. It is suitable for DSH ecosystem users who prefer lightweight, zero-dependency solutions. For more information and source code, visit the GitHub repository.