Introduction

In the development or usage scenarios of DSH (DeepSeek Harness), after an Agent completes a task, an immediate feedback mechanism is needed. A way to notify users when scripts or scheduled tasks run in the background is also required. The existing Web UI lacks this lightweight message notification capability.

dsh-localnotify is a DSH client plugin that adds a “Notifications” entry to the sidebar and opens a full-screen notification center, solving the issues above.

Installation and Activation

The installation process is very simple; just use the officially provided installation command.

dsh plugin --profile web add github:yakoylp/dsh-localnotify

After installation, restart the dsh web service to load the client bundle. After restarting, a bell icon 🔔 “Notifications” appears next to Settings at the bottom of the sidebar, and the unread count is displayed as a badge on the icon.

Core Features

Sidebar Entry and Notification Center

The sidebar “Notifications” entry is located next to Settings at the bottom of the left sidebar, with an unread-count badge.
Clicking the entry opens a full-screen overlay (shell.overlay), and the card list displays single-line previews of the title and body.

The notification center supports the following operations and filters:
* Visual level styling: colors are used to distinguish info (brand color), success (green), warn (yellow), and error (red).
* Filtering and search: supports filtering by time (all / today / last 7 days / last 30 days), source (agent / cron / cli, etc.), and sort order (newest / oldest / unread first), as well as real-time search by title and content.
* Details and copy: clicking a card opens a detail view (including full timestamp, level, source, and full text), with one-click copy support for the title, body, or entire content. The detail view automatically marks the notification as read when opened.
* Management actions: supports marking all as read, deletion (with a confirmation prompt), and checking the current page size (10 / 20 / 50 / 100 items per page).

Real-time updates and multilingual support

  • Real-time refresh: while the page is open, it polls every 3 seconds; after closing, it synchronizes the badge every 30 seconds.
  • Multilingual support: interface copy automatically follows the DSH Web language setting (zh / en).

Data persistence and automatic cleanup

  • Storage location: saved by default to ~/.dsh/notify/notifications.json (the DSH_HOME environment variable takes precedence).
  • Write mechanism: supports three methods: Agent tools, CLI commands, and directly modifying the JSON file. Write operations use atomic replacement (temporary file + rename), so partially corrupted files are avoided.
  • Automatic cleanup: supports configuring the retention period (retainDays); expired notifications are automatically deleted on write. It is disabled by default, but a 500-notification cap always serves as a fallback.

Usage

Writing via CLI

The plugin provides a dsh-localnotify CLI tool, suitable for use by scripts or scheduled tasks.

# 新增通知（默认 info 级别）
dsh-localnotify add "任务完成" -b "转换结果已生成"

# 指定来源与级别
dsh-localnotify add "提醒" --source cron --level warn

# 列出通知（* 为未读，[E]/[W]/[OK] 为级别标记）
dsh-localnotify list --unread

# 查看或设置自动清理保留天数（0=永久）
dsh-localnotify config --retain-days 7

# 立即执行一次清理
dsh-localnotify prune

Agent tool

In DSH Agent conversations, the plugin registers a notify_add tool. The Agent can call this tool when a task is completed to write a notification.

notify_add(title: "文档转换完成", body: "23 页扫描件已转为 Markdown...", level: "success")

JSON file format

Notification data is stored in JSON format with the following structure:

{
  "version": 2,
  "notifications": [
    {
      "id": "n_mtisij3d_q32zcn",
      "title": "任务完成",
      "body": "转换结果已生成，共 23 页。",
      "createdAt": 1788274582825,
      "read": false,
      "source": "agent",
      "level": "success"
    }
  ],
  "settings": { "retainDays": 0 }
}

Architecture and Limitations

  • Architecture: the plugin consists of a Node section (Host-side API registration and storage logic) and a browser section (Client-side UI rendering and polling).
  • Real-time updates: currently uses a polling mechanism (small same-origin requests); real-time Host → Client push has not been implemented.
  • Concurrency safety: concurrent writes from multiple processes rely on atomic rename operations, so the last writer wins under extreme concurrency. Write operations within a single process are serialized.
  • File transparency: the file can be modified by external tools; reads use the current contents as the source of truth.

Summary

dsh-localnotify provides DSH with a localized, dependency-free notification solution. It supports active push by the Agent during conversations and passive writes from scripts, and, combined with the full-screen notification center and level-based classification, it effectively improves the feedback efficiency of workflows.