DSH Plugins Marketplace

DSH Plugins

Plugins

/

dsh-dock-attention

i

dsh-dock-attention

Manifest valid

Bounce a Dock icon when DeepSeek Harness needs your attention and the window is in the background — a DSH Host plugin with a native macOS beacon.

hasBundlePatch

dsh-dock-attention

License Platform DeepSeek Harness Release

A Host plugin for DeepSeek Harness that bounces a Dock icon when the agent needs you and the Harness window is not frontmost.

icon

The plugin watches the durable session event feed — approvals, agent questions and finished turns — and only then reaches for the Dock. If you are already looking at Harness, nothing happens: attention is for when you are away, not for interrupting the window you are in.

Why a separate beacon in the Dock

The Dock tile of the Desktop app belongs to its Electron main process, and app.dock.bounce() is a main-process API. A Host plugin runs in a separate Node child process (the private Desktop Host) and cannot call it; the Dock additionally refuses cross-process "bounce another app's tile" requests unless the caller carries a private entitlement. That makes "make the DSH icon bounce" impossible for a plain plugin, no matter which hook it uses.

So this plugin ships the smallest honest alternative: a native helper app, DSH Attention. When attention is needed, the Host plugin writes a request file, launches the helper in the background (open -n -g), and the helper:

  1. runs as a regular app launched with open -g, so it owns an ordinary Dock tile without becoming frontmost;
  2. asks AppKit for user attention, so that tile bounces;
  3. quits — and takes its tile with it — as soon as the Harness window comes to the front, its own icon is clicked, or the time budget runs out.

Clicking the bouncing tile activates Harness (or launches it, when it is not running). The tile has to belong to an ordinary app: a background agent (LSUIElement) that promotes itself to a regular app gets a Dock tile LaunchServices cannot reopen, so a click on it makes macOS reveal the bundle in Finder instead of activating the app — the click never reaches the helper. Versions before 1.0.2 worked that way and opened Finder instead of Harness; the beacon stays a plain regular app now.

The helper is copied once to ~/Library/Application Support/dsh-dock-attention/DSH Attention.app (quarantine flag stripped, ad-hoc signed, registered with LaunchServices) and launched from there, so its Dock tile always belongs to one stable app bundle instead of a file inside node_modules. The request and log files live next to it in runtime/; a plugin update refreshes the copy automatically.

The helper needs no Accessibility, Automation, Screen Recording or Notification permissions: focus detection uses NSWorkspace through JXA, and the bounce is AppKit's own requestUserAttention.

What triggers it

MomentEventDefault
The agent waits for an approval decisionapproval/askedon
The agent asks a question (ask_user_question, exit_plan_mode)tool/callon
A turn finished, failed, was blocked, or hit the token limitturn/endon

Silent cases: turns the user cancelled (aborted), forked or interrupted turns, and subagent sessions (unless includeSubagents: true). A bounce is also skipped when one of activeBundleIds is frontmost, when a beacon is already bouncing, or when the event arrives within minIntervalSeconds of the previous one.

Install

Plugin Manager / CLI:

dsh plugin --profile desktop add "github:ihodorchenko/dsh-dock-attention"

Plugin Manager also accepts the git URL git+https://github.com/ihodorchenko/dsh-dock-attention.git. A source archive is attached to every release.

From a local checkout:

dsh plugin --profile desktop add "link:/absolute/path/to/dsh-dock-attention"

Without Plugin Manager — point a profile patch row at the package directly (the Loader watches the profile, so a new row appears without a restart):

- insert:
    - id: dock-attention
      name: 'file:///absolute/path/to/dsh-dock-attention/index.js'
      config:
        mode: critical

The plugin only runs on macOS. On other platforms it mounts and does nothing.

Configuration

Every field is optional; the row's config mapping is merged over these defaults.

FieldDefaultMeaning
enabledtrueMaster switch.
targetBundleIdcom.deepseek.dshApp the beacon activates and watches. Point it at your browser bundle id when you run dsh web in a browser.
activeBundleIds['com.deepseek.dsh']Foreground apps that count as "already looking at Harness".
skipWhenActivetrueNever bounce while one of activeBundleIds is frontmost.
bounceOnApprovaltrueBounce when an approval is requested.
bounceOnQuestiontrueBounce when the agent asks a question.
bounceOnTurnEndtrueBounce when a turn ends (finished, failed, blocked, token limit).
includeSubagentsfalseAlso bounce for subagent sessions.
modecriticalcritical bounces until you come back (or the timeout); informational bounces repeatCount times.
repeatCount3Number of single bounces in informational mode (1–20).
timeoutSeconds30How long the beacon tile may stay in the Dock (3–300).
minIntervalSeconds3Debounce window between two bounces (0–120).
soundnullmacOS system sound name (Glass, Ping, …) or an absolute audio path; null is silent.
openUrldsh://openFallback opened by the beacon when targetBundleId is not installed.
- id: dock-attention
  name: dsh-dock-attention
  config:
    mode: critical
    timeoutSeconds: 45
    bounceOnTurnEnd: false   # only "needs you" moments
    sound: Glass

Running dsh web in Safari? Use:

config:
  targetBundleId: com.apple.Safari
  activeBundleIds: ['com.apple.Safari']

Verifying it works

node tools/self-check.mjs

The self-check compiles nothing; it installs the beacon copy, launches it, watches it through NSWorkspace, waits for it to exit, and prints the helper log tail. It also prints the installed location it launched from. Watch the Dock while it runs: a bouncing DSH Attention icon should appear and disappear after about eight seconds.

Limitations

  • macOS only. The whole mechanism is macOS-specific.
  • The beacon is a separate Dock icon, not the Harness icon itself (see "Why a separate beacon" above). It exists in the Dock only while attention is pending; clicking it returns to Harness.
  • While the beacon is active it is a regular app, so it is visible in the Dock and can appear in Cmd-Tab for those few seconds. It never takes focus on launch.
  • No notification and no sound by default — those are separate plugins. Set sound or pair it with dsh-macos-notifications if you want more than motion.
  • macOS "Reduce motion" and third-party Dock-animation tweaks can suppress the bounce animation; the plugin cannot detect that. The tile still appears.
  • macOS throttles very long critical requests; lower timeoutSeconds (10–15 s) if you want a shorter, unthrottled burst.
  • The helper is ad-hoc signed, not notarized. On first use the plugin copies it to ~/Library/Application Support/dsh-dock-attention/ and strips the quarantine flag from that copy, so git, local-checkout and zip installs all behave the same; no manual xattr command is needed.
  • If the Harness window is in the foreground, by design nothing bounces.

Troubleshooting

  • No icon appears at all — run node tools/self-check.mjs; it reports whether the helper launched at all and prints the tail of ~/Library/Application Support/dsh-dock-attention/runtime/helper.log.
  • Clicking the icon opens Finder instead of Harness — that is the pre-1.0.2 build. It started as a background agent and promoted itself to a regular app, so its Dock tile could not be reopened by LaunchServices, and it also ran from inside the package directory. Update to 1.0.2+: the beacon is a plain regular app launched from a stable Application Support copy, so a click is an ordinary Dock activation.
  • Icon appears but never bounces — check "Reduce motion" in System Settings → Accessibility, and Dock animation tweaks. The beacon log still shows requestUserAttention(...) -> id=0, which means the request was accepted (return value 0 is a valid first request id — -1 would mean the app was active).
  • The beacon appears while you are already looking at Harness — set skipWhenActive: true (the default) and make sure activeBundleIds names the right app; browser users must add their browser's bundle id.

Files

FileRole
index.jsHost plugin: session-event listeners and attention dispatch
lib/attention.jsConfig normalization, event mapping, focus probe, beacon launch
bin/DSH Attention.appNative beacon app (universal binary, ad-hoc signed)
src/helper/main.swiftBeacon source; tools/build-helper.sh rebuilds the bundle
~/Library/Application Support/dsh-dock-attention/Installed helper copy plus runtime/request.json and runtime/helper.log, written at run time
cordis.patch.ymlBundle patch that inserts the dock-attention row
locale/en.json, locale/ru.jsonPlugin Manager display metadata
icon.svg, docs/icon-1024.pngPlugin icon and app icon source

Development

node --test                        # 23 unit tests (config, event mapping, wiring, helper bundle)
bash tools/build-helper.sh         # rebuild bin/DSH Attention.app (needs Xcode CLT)
python3 tools/render-icon.py       # optional: re-render AppIcon.icns (needs Pillow)

The helper source is small enough to audit: requestAttention, the single-instance guard, the frontmost-app poll, and the click/activation forwarding are all in src/helper/main.swift. Keep it a regular app: the tests/helper.test.mjs guard fails if LSUIElement ever comes back.

License

MIT — see LICENSE. The beacon is ad-hoc signed (no Apple Developer identity), so it carries no notarization; it is launched from a local package directory and needs no quarantine escape hatch.

Comments

Loading…

Similar plugins

@apodemakeles/dsh-macos-notify

by apodemakeles

DeepSeek Harness (DSH) plugin: macOS turn-completion notifications and an unfocused-completion unread dot.

Terminal & ClientsManifest valid

★ 0

MIT

JavaScript

Nov 7, 2026

dsh plugin --profile web add @apodemakeles/dsh-macos-notify

by drydeuterium

Desktop (Windows toast) notifications for DeepSeek Harness — questions, approvals, turn end and errors. Host-side plugin, zero dependencies.

Manifest valid

★ 0

MIT

JavaScript

Oct 20, 2026

dsh plugin --profile web add dsh-desktop-notify

by AK-blank

Unofficial DSH (DeepSeek Harness) plugin: macOS Notification Center alerts when a session finishes or needs you — the banner carries the last reply, plays your system alert sound, and clicking it jumps back to the DSH page.

Tools & CapabilitiesNotifications & IntegrationsDevelopment & InfrastructureManifest valid

★ 1

MIT

JavaScript

Oct 3, 2026

dsh plugin --profile web add dsh-plugin-mac-notify

by MarJose123

DeepSeek Harness plugin: your DeepSeek API balance and the current peak/off-peak billing window, below the message input.

Manifest valid

★ 0

MIT

JavaScript

Oct 18, 2026

dsh plugin --profile web add dsh-simple-usage-info

by AITabby

A macOS-only native account-pool and provider plugin for DeepSeek Harness.

Models & ProvidersManifest valid

★ 81

MIT

JavaScript

Nov 16, 2026

dsh plugin --profile web add @dockyard-dsh/plugin

by songying2024

DeepSeek Harness (DSH) left-side bookmark dock plugin

Tools & CapabilitiesManifest valid

★ 0

MIT

JavaScript

Aug 22, 2026

dsh plugin --profile web add dsh-bookmarks-dock