Introduction

DSH sessions often run for long periods in the background. When a task completes, manual input is required, or an error occurs, reviewing logs directly in the terminal is not intuitive and key information can easily be missed. This plugin reminds you through the macOS Notification Center; clicking a notification switches you back to the DSH page. It is suitable for running DSH on unattended or remote servers.

What Is This

This is an unofficial DSH client plugin maintained by AK-blank. It is a Host-side bundle that focuses on listening to Host events and pushing alerts to the macOS Notification Center via terminal-notifier or the built-in osascript. It does not include browser-side rendering code.

Core Features

The plugin listens to the following 4 Host events and sends notifications:

  • Task completion: when the agent/status state changes from running to idle.
  • Answer required: when an agent call to ask_user_question is blocked.
  • Approval required: when the agent is waiting for an approval decision.
  • Execution error: when a step or turn encounters an error.

By default, subagents remain silent, and non-urgent notifications are coalesced within 5 seconds to avoid a flood of notifications.

Installation and Enabling

Use the official CLI to install. After installation, you must restart the dsh web or dsh tui process for the plugin to take effect.

dsh plugin --profile web add github:AK-blank/dsh-plugin-mac-notify

After installation is complete, the plugin appears on the DSH Plugins page and can be manually toggled.

Configuration

The plugin itself has no configuration options; all settings must be overridden in cordis.patch.yml (applied after the bundle layer):

- id: mac-notify
  name: 'dsh-plugin-mac-notify'
  config:
    enabled: true
    sound: Ping
    notifyOnApproval: false
    url: 'http://127.0.0.1:3080'

Main configuration items include:
* enabled: master switch.
* sound: sound name (such as Ping, Glass) or off.
* onClick: click behavior: focus (focus the existing tab), open (open a new tab), or none.
* notifier: choose auto (recommended) or force use of osascript.
* minIntervalMs: minimum interval for non-urgent notifications (default 1500ms).

Typical Usage

After installation, you can run the following command for a self-test and ensure all 57 assertions pass:

node selftest.mjs

If you need to debug without actually sending notifications, you can use an environment variable:

DSH_MAC_NOTIFY_DRY_RUN=1 dsh web

Notes

  1. Platform limitation: macOS only. On other platforms, the plugin will activate and log, but it will not send notifications.
  2. Dependency: The click-to-open feature depends on terminal-notifier. If it is not installed, the plugin falls back to osascript, but cannot perform the click action.
    • Install command: brew install terminal-notifier
  3. System permissions: The plugin requires notification permission and macOS Automation permission (the system will prompt on the first click).
  4. Restart required: After updating the plugin, you must restart dsh web or dsh tui to load the new code.

Conclusion

This plugin uses native notifications to solve the DSH status synchronization problem while it runs in the background. See the GitHub repository for the source code and additional debugging information.