dsh-notify

English | [中文](#chinese)

A DeepSeek Harness (dsh) Web GUI plugin that sends browser desktop notifications when a conversation completes or the agent is waiting for your confirmation.

Stop checking back on long-running tasks — work in another window and let the system tray tell you when the agent finished or needs an approval.

Features

• Noise gate — notifies only when the page is hidden or the affected session is not the selected one
• Click to focus — clicking a notification focuses the window; auto-closes after 10 s
• All sessions covered — watches the full session list, not just the open one
• Silent degradation — denied permission or missing Notification API never errors
• Zero host cost — host half is an empty placeholder; pure JavaScript, no build step

Install

# from git (no build step, no allowBuilds needed)
dsh plugin --profile web add github:pedesdestiny/dsh-notify

# or a local checkout
dsh plugin --profile web add /path/to/dsh-notify

# restart to load
dsh --profile web

Open http://127.0.0.1:3080 and allow the notification permission prompt. If you previously denied it, re-enable via the browser's site settings (lock icon → Notifications).

How it works

┌─ dsh host ────────────────────────────────────┐
│  cordis.patch.yml  →  inserts a Loader row    │
│  index.js          →  empty (placeholder)     │
└──────────────┬────────────────────────────────┘
               │ dsh.client declaration →
               │ bundle injects window.__DSH_BOOT__
┌──────────────▼────────────────────────────────┐
│  Browser                                       │
│  client.js → registers into shell.overlay slot │
│    └─ invisible component, useSessions watches │
│       all sessions                             │
│         ├─ running edge  → completion notice   │
│         └─ pending edge  → confirmation notice │
└────────────────────────────────────────────────┘

• client.js — browser half: an invisible React component mounted in the always-rendered shell.overlay slot. It watches session-list snapshots through the standard useSessions hook, detects running / pendingInteraction edges, and fires the Notification API
• index.js — empty host placeholder for the Loader row
• cordis.patch.yml — bundle layer inserting the plugin row
• package.json — declares dsh.bundle and dsh.client (depends on dsh-client-runtime / dsh-client-ui-layout)

Limitations

• Requires the GUI tab to remain open (background tab is fine); no notifications when the browser is fully closed
• Permission is granted per site origin (127.0.0.1:3080)
• The first snapshot is a baseline: sessions that finished before page load do not notify

License

MIT

---

<a id="chinese"></a>

dsh-notify（中文）

DeepSeek Harness (dsh) Web GUI 插件：在对话完成或等待用户确认时，向你的操作系统发送浏览器桌面通知。

挂后台跑长任务、切去别的窗口工作时，不必再频繁回头检查对话状态——任务跑完或 Agent 需要你批准操作时，系统右下角会弹出通知。

功能

特性：

• 免打扰门槛 — 仅当页面处于后台，或受影响的会话不是当前选中的会话时才通知；你正盯着看的对话不会打扰你
• 点击聚焦 — 点击通知回到浏览器窗口
• 自动关闭 — 通知 10 秒后自动消失
• 多会话覆盖 — 监听全部会话（含后台会话），不只当前打开的
• 静默降级 — 浏览器通知权限被拒绝或 API 不可用时，插件保持沉默，绝不报错
• 零宿主开销 — 宿主端为空实现，全部逻辑在浏览器端；纯 JavaScript，无构建步骤

安装

方式一：git 安装（推荐）

dsh plugin --profile web add github:pedesdestiny/dsh-notify

本插件无构建步骤，git 安装开箱即用，无需 allowBuilds 授权。

方式二：本地目录

dsh plugin --profile web add /path/to/dsh-notify

生效

dsh --profile web   # 重启 dsh 加载插件

打开 http://127.0.0.1:3080，浏览器弹出通知权限请求时点击允许。

> 提示：如果之前拒绝过权限，需要在浏览器站点设置中（地址栏锁图标 → 通知）手动改为允许。

验证

1. 打开 Web GUI，切到别的窗口（让页面进入后台） 2. 发送一个任务给 Agent 3. 任务完成时，系统应弹出「对话完成」通知 4. 触发一个需要批准的操作（如越权文件写入），系统应弹出「等待批准」通知

工作原理

┌─ dsh 宿主 ─────────────────────────────┐
│  cordis.patch.yml  →  插入 Loader 行    │
│  index.js          →  空实现（占位）     │
└──────────────┬─────────────────────────┘
               │ dsh.client 声明 →
               │ bundle 注入 window.__DSH_BOOT__
┌──────────────▼─────────────────────────┐
│  浏览器                                  │
│  client.js → 注册进 shell.overlay slot   │
│    └─ 隐形组件 useSessions 监听全部会话   │
│         ├─ running 边沿  → 对话完成通知   │
│         └─ pending 边沿  → 等待确认通知   │
└────────────────────────────────────────┘

• client.js — 浏览器端核心：一个挂载在常驻 shell.overlay slot 的隐形 React 组件，通过标准 useSessions 钩子监听完整会话列表快照，检测 running 与 pendingInteraction 的状态边沿并触发 Notification API
• index.js — 宿主端空实现，仅为 Loader 行提供合法模块
• cordis.patch.yml — bundle 层，向配置树插入插件行
• package.json — 声明 dsh.bundle（组合包）与 dsh.client（浏览器面，依赖 dsh-client-runtime / dsh-client-ui-layout）

已知限制

• 通知依赖浏览器 Notification API：GUI 标签页必须处于打开状态（后台标签可以）；浏览器完全关闭时不会通知
• 通知权限按浏览器站点（127.0.0.1:3080）粒度授予
• 首次快照作为基线：页面加载时已经在运行的会话，其完成事件仍会正常通知；加载前已结束的不会

许可证

MIT