Skip to main content
C

dsh-mac-notify

carbenelee/dsh-mac-notify

Native macOS notifications for DSH: task completion, failures, approval requests, questions and plan reviews. A small bundled helper app lets banners use the DSH icon and opens DSH on click; the notification tone can be any audio file.

Install

dsh plugin --profile web add github:carbenelee/dsh-mac-notify

README

dsh-mac-notify

Native macOS notifications for DeepSeek Harness (DSH): a banner appears when a task completes, fails, needs your approval, or needs an answer — so you do not have to babysit the window.

中文说明

Four banners

macOS only. The package declares dsh.bundle.platforms: ["darwin"], so Windows and Linux hosts skip the bundle instead of installing a plugin that can never fire.

What it notifies

MomentDSH eventBanner
✅ Task completeturn/end → completedduration + your prompt (+ last answer line)
❌ Task failedturn/end → error / max-tokenserror message + task
🔐 Approval neededapproval/requesttool name + reason
❓ Answer neededuser-questions/requestthe question text (count when several)
📋 Plan awaiting reviewuser-questions/request with plan-reviewdedicated subtitle
⏸ Task blockedturn/end → blockedoff by default

Subagent turns are silent by default: every subagent ends turns constantly and would spam you; only the session you are watching announces itself.

Install

Desktop app (DeepSeek Harness.app)

The desktop profile is managed exclusively by the Electron app, so dsh plugin --profile desktop ... is refused. Use Plugins → Install in the sidebar with:

link:/absolute/path/to/dsh-mac-notify     # local checkout
github:CarbeneLee/dsh-mac-notify          # straight from GitHub

The desktop app ships HMR, so the bundle usually mounts without a restart; quit and reopen the app only if no banner appears.

Web profile / custom profiles (CLI)

dsh plugin --profile web add dsh-mac-notify                    # from npm (recommended)
dsh plugin --profile web add github:CarbeneLee/dsh-mac-notify  # or straight from GitHub

The default backend is auto: Electron, then the native helper, then terminal-notifier, then osascript. On first mount the plugin builds DSHNotifier.app in the background if it is missing (Xcode Command Line Tools required, a few seconds); until it finishes, notifications still arrive through osascript with the Script Editor icon. Set DSH_MAC_NOTIFY_NO_BUILD=1 to opt out.

Manual wiring

Add the dependency and the bundle to ~/.dsh/profiles/<profile>/package.json:

{
  "dependencies": { "dsh-mac-notify": "link:/path/to/dsh-mac-notify" },
  "dsh": { "profile": { "bundles": ["...", "dsh-mac-notify"] } }
}

Then install inside the profile with the pnpm the app ships:

cd ~/.dsh/profiles/desktop
node "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs" install

Verify

  1. System notifications first, no plugin needed:
    node scripts/notify-demo.mjs
    
  2. With the plugin mounted, ask "send a test notification" — the model calls mac_notify_test and returns the active backend and config.
  3. Set debug: true to append every delivery to ~/.dsh/dsh-mac-notify/debug.log.

Configure

Overrides live in the profile's cordis.patch.yml:

- id: dsh-mac-notify
  config:
    appName: DeepSeek Harness
    notifyOnComplete: true
    notifyOnError: true
    notifyOnApproval: true
    notifyOnQuestion: true
    suppressWhenFocused: false
    backend: osascript
    completeSound: Glass
    debug: false
FieldDefaultMeaning
enabledtruemaster switch
appNameDeepSeek Harnessbanner title, and the app name used for focus suppression
bundleIdcom.deepseek.dshapp activated on click
localeautozh / en, auto reads LANG
notifyOnCompletetruetask complete
notifyOnErrortruefailure / output limit
notifyOnApprovaltrueapproval requests
notifyOnQuestiontruequestions, choices, plan review
notifyOnBlockedfalseblocked turns
includeSubagentsfalseinclude subagent turns (noisy)
suppressWhenFocusedfalseskip while the DSH window is frontmost
completeSoundGlassmacOS sound name
errorSoundBasso
approvalSoundPing
questionSoundPing
completeSoundFile""audio file for the tone; wins over the named sound
errorSoundFile""
approvalSoundFile""
questionSoundFile""
backendautosee below
helperPath""helper binary, defaults to $DSH_HOME/dsh-mac-notify/DSHNotifier.app/...
command""command for backend: command
minIntervalMs300throttle for burst notifications
maxBodyChars220body budget
maxLabelChars70task label budget
debugfalsewrite debug.log

Sound names are the system ones (Glass, Ping, Basso, Submarine, Hero, …); "" is silent.

Reuse another app's tone (WeChat / QQ)

*SoundFile accepts anything afplay can play (caf / aiff / wav / mp3), so the notification can sound exactly like WeChat:

mkdir -p ~/.dsh/dsh-mac-notify/sounds
cp /Applications/WeChat.app/Contents/Resources/notify.caf \
   ~/.dsh/dsh-mac-notify/sounds/wechat-notify.caf
- id: dsh-mac-notify
  config:
    completeSoundFile: "~/.dsh/dsh-mac-notify/sounds/wechat-notify.caf"
    errorSoundFile: "~/.dsh/dsh-mac-notify/sounds/wechat-notify.caf"
    approvalSoundFile: "~/.dsh/dsh-mac-notify/sounds/wechat-notify.caf"
    questionSoundFile: "~/.dsh/dsh-mac-notify/sounds/wechat-notify.caf"

Copy the file into your own directory instead of referencing the app bundle, so an app update cannot break it. Each event may use its own tone; empty falls back to the named system sound.

Backends

backendNotes
helper (recommended)posts through the bundled DSHNotifier.app: the banner wears DSH's own icon, and clicking it activates DeepSeek Harness. Build it once with sh scripts/build-helper.sh
osascriptdisplay notification, zero dependencies, works from any macOS process; Notification Center attributes it to Script Editor and the banner is not clickable
electronnative Electron notification: attributed to DeepSeek Harness, click activates the app. Only works where the plugin host can load the electron module — the shipped DSH desktop build (Electron 44) does not expose it to plugins, so this backend falls back (see the debug log)
terminal-notifierif brew install terminal-notifier is present; supports grouping
commandpipe to your own command; the payload arrives as DSH_NOTIFY_TITLE/SUBTITLE/BODY/SOUND/GROUP
auto (default)Electron → helper → terminal-notifier → osascript

command example (webhook, noti, a script of yours):

backend: command
command: 'curl -s -X POST -H "Content-Type: application/json" -d "{\"text\":\"$DSH_NOTIFY_BODY\"}" https://example.com/hook'

Icon and click behaviour (helper backend)

macOS draws a notification's icon from the bundle that posted it: AppleScript shows Script Editor, and terminal-notifier 3.x dropped -appIcon because the system forbids overriding it. The repo therefore ships a tiny native app, DSHNotifier.app:

  • it borrows DeepSeek Harness's icon.icns, so the banner shows the DSH whale mark;
  • clicking the banner launches it, it brings DeepSeek Harness to the front and quits immediately (no dock icon, no background process);
  • the first notification asks once for permission ("DeepSeek Harness wants to send you notifications") — allow it in System Settings → Notifications.

Build it once (Xcode Command Line Tools required):

sh scripts/build-helper.sh     # installs to ~/.dsh/dsh-mac-notify/DSHNotifier.app

then enable it:

- id: dsh-mac-notify
  config:
    backend: helper

Deep-linking to one session is not possible yet: DSH registers the dsh:// scheme but the desktop app has no URL handler, so a click can only raise the app, leaving it on the page it was last showing.

Troubleshooting

  • No banner: System Settings → Notifications → allow Script Editor (osascript backend) or DeepSeek Harness (electron backend); check Focus / Do Not Disturb.
  • Nothing after install: restart the desktop app; confirm dsh-mac-notify is in dsh.profile.bundles of ~/.dsh/profiles/desktop/package.json.
  • Completion works, approvals do not: approvals only exist under the ask policy; the banner is emitted regardless of whether an answerer takes the request.
  • Privacy: banner text also shows on the lock screen. It contains the first line of your prompt, tool names and question text — lower maxBodyChars or switch events off if that matters.

How it works

Host-only, zero runtime dependencies; it reads no files and opens no sockets:

approval/request       ──┐
user-questions/request ──┼──► compose banner ──► sender.send() ──► Notification Center
session/event turn/end ──┘                        ├─ electron Notification
                                                  ├─ terminal-notifier
                                                  ├─ osascript
                                                  └─ custom command
  • Listeners register with { global: true, prepend: true }, send the banner, then hand the request back with next() — approval outcomes are never changed, and a failing notification can never block a task.
  • Each turn remembers the first human prompt and the last answer, which become the banner text.
  • Delivery is fire-and-forget; errors only reach the debug log.

Development

npm test                      # 18 node:test cases, no DSH required
node scripts/notify-demo.mjs  # send a real notification
dsh/index.js    event routing + wording
dsh/notify.js   backends (osascript / electron / terminal-notifier / command)
dsh/config.js   defaults and validation
dsh/text.js     clamping and duration formatting
test/           node:test suite

Limitations

  • macOS only; other platforms skip silently.
  • osascript banners have no click action; use backend: electron for click-to-activate.
  • Profile changes hot-apply through HMR; a restart is the fallback when a re-composition is refused.
  • Notifications carry no window identity: every session in the profile shares one stream.

License

MIT

Related plugins