Preface¶

When running long tasks with DeepSeek Harness (dsh), the terminal isn’t always kept open, and the Web UI might be switched away from. If a task finishes, the model needs to ask a question, or approval is pending, developers need a low-intrusion way to know “it’s time to come back.”

pitetow/dsh-notify-on-complete is a DSH plugin written for this purpose: it sends desktop notifications when a run finishes, when the model calls ask_user_question, or when waiting for sandbox privilege escalation / tool permission approvals. The plugin is positioned as an extension, licensed under MIT, with version 0.3.0 in package.json.

Core Features¶

Run Completion Notifications¶

The plugin sends a notification after a top-level run finishes, differentiating the notification body based on the result:

• completed
• error
• aborted
• max-tokens

The plugin only notifies for top-level runs, filtering out subagent sessions, using the following check:

header.origin === 'subagent'

This reduces redundant notifications from multiple sub-sessions within a single CLI run.

In-Session Instant Alerts¶

In addition to run completion, the plugin also triggers notifications during a session:

• Model calls ask_user_question
• Waiting for sandbox privilege escalation approval
• Waiting for tool permission approval

These scenarios typically mean the task is waiting for user input. The plugin provides fine-grained control through the following configuration options:

• onBlocked
• onQuestion
• onApproval

Zero Runtime Dependencies¶

The plugin does not depend on dsh internal packages. Notifications are sent via Node.js child_process.spawn as detached child processes, avoiding interference from the main process’s exit path.

Cross-Platform Notification Commands¶

The plugin selects the notification command based on the current platform:

• macOS: osascript
• Linux: notify-send, falling back to kdialog if unavailable
• Windows: PowerShell

Unsupported platforms are skipped with a warning at load time, rather than throwing errors on every event.

System Notification Sounds¶

The plugin supports system notification sounds:

• macOS: Glass
• Windows: SystemSounds
• Linux: canberra-gtk-play, falling back to paplay if unavailable

Sounds can be disabled via configuration:

sound: false

Installation and Enablement¶

Prerequisites¶

You need:

• Node.js ^22
• An installed dsh CLI
• pnpm

Plugin dependencies:

@deepseek-ai/cordis@^4.0.1

This dependency is provided by the dsh CLI and will be resolved automatically during pnpm installation.

One-Click Installation¶

Default installation command:

curl -fsSL https://raw.githubusercontent.com/pitetow/dsh-notify-on-complete/main/scripts/install.sh | bash

This command executes a remote script. It’s recommended to review:

scripts/install.sh

in the repository before installing.

The installation script does not overwrite existing source directories by default. To force an update, use:

curl -fsSL https://raw.githubusercontent.com/pitetow/dsh-notify-on-complete/main/scripts/install.sh | bash -s -- --force

Note: --force deletes and re-downloads the source code, so local edits in that directory will be lost.

Installing to a Different Profile¶

The default installation targets the web profile. To install to the headless profile:

curl -fsSL https://raw.githubusercontent.com/pitetow/dsh-notify-on-complete/main/scripts/install.sh | bash -s -- --profile headless

Verifying the Installation¶

You can check whether the plugin appears in the current profile’s configuration:

dsh --profile web --dump-config | grep -n notify-on-complete

If you see entries related to notify-on-complete, the plugin has been added to the current profile’s configuration tree.

To apply changes:

• CLI one-shot runs: takes effect on the next run
• Web GUI: requires restarting the dsh web process

Typical Usage¶

Updating the Plugin¶

Method 1: Use the installation script with force update.

curl -fsSL https://raw.githubusercontent.com/pitetow/dsh-notify-on-complete/main/scripts/install.sh | bash -s -- --force

Method 2: Manually update the local source.

cd ~/.dsh/plugins/dsh-notify-on-complete
git pull
pnpm install
pnpm run build
dsh plugin --profile web add link:.

After completion, restart or re-run the corresponding dsh process.

Uninstalling the Plugin¶

dsh plugin --profile web remove dsh-notify-on-complete
rm -rf ~/.dsh/plugins/dsh-notify-on-complete

Restart dsh after uninstalling.

Use Cases and Considerations¶

Suitable for these situations:

• Running long DSH tasks without wanting to constantly monitor the terminal
• The model frequently calls ask_user_question and needs user responses
• Tasks trigger sandbox privilege escalation or tool permission approvals
• Using macOS, Linux, or Windows, and wanting system notification alerts

Things to note before installation:

1. The plugin runs with the permissions of the current dsh process; it’s recommended to review the source code and license first.
2. curl | bash executes a remote script; review scripts/install.sh before using it.
3. The installation script does not overwrite existing directories by default; before using --force, confirm there are no local modifications you need to keep.
4. For Web GUI scenarios, the dsh web process needs to be restarted for changes to take effect.

Project Repository¶

GitHub:

https://github.com/pitetow/dsh-notify-on-complete