dsh-thinking-notifier
A DeepSeek Harness (DSH) plugin that shows a small always-on-top desktop popup in the bottom-right corner of your screen. It mirrors the AI's thinking status in real time and alerts you when the AI requests permission, waits for a choice from you, or finishes thinking — even when you are working in other apps, browsers, or virtual desktops.
中文说明见 README.zh.md
Features
| State | Popup | Sound |
|---|
| AI is thinking | DeepSeek-blue pulsing dot + AI 正在思考… + elapsed time. Auto-collapses to a 25 px slim right-edge tab after 5 s; hover or click the tab to expand it again | none |
| AI waits for your choice | Violet pulsing dot + AI 正在等待你的选择 + the question heading, the first question's option labels (选项：A / B, （可多选） for multi-select, （共 N 问） when several questions arrive at once) and how long it has been waiting. Stays expanded until you answer | system Question |
| AI requests permission | Amber pulsing dot + AI 请求权限 + session/tool name. Stays expanded until you decide | system Exclamation |
| AI finished thinking | Green dot + AI 已完成思考, auto-hides after 12 s | system Asterisk |
| Idle | Hidden | none |
- DeepSeek-style dark card (
#1E2235 / #4D6BFE).
- Always-on-top frameless window, bottom-right, visible over any application.
- Auto-collapses into a 25 px slim right-edge tab after 5 s while the AI is thinking, so it stays visible without blocking desktop controls.
- Hover or click the edge tab to expand it manually; new turns, questions, permission requests, and completions expand it automatically.
- Click the X button to dismiss the current popup; the next new turn, question, permission request, or completion will show it again.
- Questions are shown with their options, which is enough to know what is being decided; the answer itself is still given in the DSH Web UI (the popup is read-only by design).
- Multiple sessions are summarized automatically.
- The popup process stays alive while DSH runs; it exits ~15 s after the status endpoint becomes unreachable.
- No browser extension required; the popup is a native desktop window.
How it works
DSH process
└─ lib/index.js (host plugin)
├─ listens to session/event: turn/start, turn/end, approval/asked, approval/decided, session/title
├─ rebuilds existing session state from ctx.sessions.list() at startup
│ (a session whose log ends inside an open turn is treated as not running)
├─ wraps ctx.userQuestions.ask to observe ask_user_question
│ (that state produces no session event, and a second UI provider cannot be registered)
├─ serves a local status JSON at http://127.0.0.1:7389/status
└─ launches the desktop popup process
├─ Windows: desktop-popup.ps1 (PowerShell + WPF)
└─ macOS/Linux: desktop-popup.py (Python 3 + tkinter)
Desktop popup
├─ polls /status every second
├─ renders the DeepSeek-style card (question/pending/running/done/idle)
├─ plays a system sound on question/pending/done transitions
├─ auto-collapses to the right edge while running; stays expanded while waiting for you
└─ hides while idle, keeps running in the background
Status JSON
GET http://127.0.0.1:7389/status returns:
{
"ok": true,
"mode": "question",
"statusText": "AI 正在等待你的选择",
"sessionText": "Choose Mode",
"detailText": "选项：样式 A / 样式 B（可多选）",
"timeText": "已等待 00:12",
"pendingKind": "question",
"pendingTool": null,
"runningSince": null,
"doneAt": null,
"questionCount": 1,
"questionSince": 1791374946369,
"appUrl": "http://127.0.0.1:3080",
"now": 1791374946369
}
mode priority: pending (an approval is waiting) > question (a question is waiting) > running > done (shown for 12 s) > idle.
pendingKind is approval or question. timeText is the thinking timer while running and the waiting time while question; detailText carries the first question's options.
Installation
From a local checkout
cd dsh-thinking-notifier
dsh plugin --profile web add .
# Restart DSH web so the host plugin is loaded
dsh web
From npm (once published)
dsh plugin --profile web add dsh-thinking-notifier
dsh web
Uninstall
dsh plugin --profile web remove dsh-thinking-notifier
Configuration
| Environment variable | Default | Description |
|---|
DSH_THINKING_NOTIFIER_PORT | 7389 | Local status server port. If busy, the next 10 ports are tried. |
DSH_THINKING_NOTIFIER_NO_POPUP | unset | Set to 1 to run the status server without launching the desktop popup (headless, tests). |
Requirements
- DeepSeek Harness Web UI (
dsh web)
- Node.js
^22.19.0 || >=24.0.0
- Windows: Windows 10/11 with PowerShell 5.1+ (built in)
- macOS/Linux: Python 3 with
tkinter
Verification status
Being explicit about what has actually been tested, so nobody is surprised:
| Area | Status |
|---|
| Thinking / done states, popup geometry, sounds, single instance | verified on Windows 10/11 (PowerShell 5.1 + WPF) |
Question state (ask_user_question) | verified end to end in a live DSH session (a real question drove the popup into the waiting state, and it cleared when the answer arrived), against the real ctx.userQuestions service in a cordis context, and by the smoke test |
| Permission alert (amber) | verified only with the mock status service. On a Windows DSH install without a confining sandbox, an out-of-workspace write is not intercepted, so no approval is raised by the runtime; the request only appears when a tool call explicitly asks for a sandbox_permissions escalation or a pre-execute hook returns ask |
desktop-popup.py (macOS/Linux) | never run on real hardware — syntax-checked only |
Popup process stacking after repeated dsh web restarts | the launcher kills stale popups for its own port before starting a new one; verified for a single restart cycle |
Development
# status-machine smoke test (fake cordis context, no popup, port 17389)
npm test
# render the popup against a mock status service, on a spare port
node tools/mock-status.mjs question --port 17389
powershell -NoProfile -ExecutionPolicy Bypass -File desktop-popup.ps1 -Port 17389 # Windows
python3 desktop-popup.py --port 17389 # macOS/Linux
Use a spare port for popup experiments: the real popup on 7389 is left alone, because the plugin only cleans up popup processes belonging to its own port.
Project structure
dsh-thinking-notifier/
├── lib/
│ └── index.js # host plugin: state machine + status service + popup launcher
├── desktop-popup.ps1 # Windows native popup (PowerShell + WPF)
├── desktop-popup.py # macOS/Linux native popup (Python 3 + tkinter)
├── cordis.patch.yml # DSH bundle patch for persistent mounting
├── test/
│ └── status-smoke.mjs # status-machine smoke test
├── tools/
│ └── mock-status.mjs # mock status service for offline popup testing
├── package.json # npm package + dsh.bundle declaration
├── README.md # English readme
├── README.zh.md # Chinese readme
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE
Troubleshooting
Debug logs are written to:
~/.dsh/tn-plugin.log — host plugin lifecycle, popup launcher, question watcher.~/.dsh/tn-launcher.log — PID of the popup process created by the launcher.~/.dsh/tn-popup-debug.log — popup script lifecycle and polling errors.
If the popup does not appear after restarting dsh web, check those logs first.
Note that popup launcher exit: code=0 in tn-plugin.log is expected: the plugin spawns a one-shot launcher which starts the real popup process and then exits.
License
MIT
