The plugin ecosystem of DeepSeek Harness (DSH) allows features to be extended through namespaces. When developing or debugging agents, it is important to track turn completion or handle permission requests. The dsh-macos-notify plugin addresses the need to track turn completion or handle permission requests during agent development or debugging by displaying banners in the macOS Notification Center.

Core Features

The plugin consists of a Host half and a browser half. The Host half listens to agent events and invokes native macOS notifications, while the browser half provides a settings page for user configuration. Main features include:

  1. Native macOS Notification Center banners: Uses /usr/bin/osascript to invoke system-native notifications.
  2. Trigger timing: Triggered when an agent turn ends or when permission requests arrive.
  3. Independent settings page: Provides a dedicated “Notifications” settings section instead of a simple card.
  4. Custom configuration: Allows configuring sound, title, and content separately for each trigger action (such as turn completion, turn failure, and permission requests).
  5. Variable replacement: Supports using variables in titles and content, such as {turn} (turn number), {tool} (tool name), and {error} (error message).
  6. Banner testing: Provides a test button to preview banner effects and verify whether the configuration is correct.

Installation

The installation process does not require build steps because build artifacts (lib/) are already under version control.

dsh plugin --profile web add github:WShihan/dsh-macos-notify

Configuration and Usage

Settings Page Configuration

After installing the plugin and composing a settings provider (for example, @deepseek-ai/dsh-settings-file), an independent Notifications page will appear in the settings panel. You can configure the following here:

  1. Notification timing: Toggles for turn completion, permission requests, or notifying only for your own sessions.
  2. Action configuration: For each trigger action (such as completed, error, and approval), configure its sound, title, and content.
  3. Testing: Click the “Test” button to immediately send a banner and preview the current sound and text effects.

Code Configuration

It can also be configured via cordis.yml or $DSH_HOME/settings.yaml. Supported configuration items include:

  • notifyOnTurnEnd: Whether to notify at the end of each turn (default true).
  • notifyOnApproval: Whether to notify when permission requests occur (default true).
  • topLevelOnly: Whether to notify only top-level sessions (default true).
  • sounds.<operation>: Set the sound for each operation (supports macOS system sounds, such as Glass, Ping, and Basso, or none for silence).
  • messages.<operation>.title / messages.<operation>.message: Set the banner title and content, with variable replacement supported.

Variable Description

Titles and content support the following variables:

  • {turn}: The number of the completed turn.
  • {tool}: The name of the tool that requires authorization.
  • {error}: Failure information (turn failure action only).
  • {reason}: The reason provided by the requester (permission request action).

Notes

  1. Dependence on a settings provider: The settings page controls require the macos-notify namespace, which requires support from the settings service. After installation, ensure that a settings provider such as dsh-settings-file is composed to make the settings page visible.
  2. Communication method: The Host half and the browser half communicate through namespaces and are unaware of each other’s code.
  3. Handling unknown events: Turn-end reasons that the plugin does not recognize fall back to “turn completed” and use that action’s sound and text.
  4. Build artifacts: The lib/ directory is under version control, so no build scripts need to be run during installation.

Reference Resources