cc-dsh-notifier

Windows desktop notifications for Claude Code and DeepSeek Harness sessions
Permission requests · Questions · Waiting for input · Click-to-return

English · 中文

cc-dsh-notifier raises a native Windows toast with sound when an agent needs your attention and you are not looking at its window. It serves Claude Code through its hook system and DeepSeek Harness through a small bundle plugin, sharing one daemon pipeline. Clicking a toast returns you to the session window. Zero third-party npm dependencies.

Features

Quick Start

Prerequisites

• Windows 10 or 11
• Node.js 18 or later
• Python 3 with the winrt packages: pip install winrt-runtime winrt-Windows.UI.Notifications winrt-Windows.Data.Xml.Dom

Install (Claude Code)

node scripts/install.mjs

The installer backs up ~/.claude/settings.json, injects five hooks, registers the cc-notifier AppUserModelID, and writes the default config. Open a new Claude Code session afterwards.

Install (DeepSeek Harness)

Recommended — download the tarball from the latest release and install it (no repository clone, no credentials):

dsh plugin --profile web add ./cc-dsh-notifier-0.1.4.tgz
dsh plugin --profile dsh-tui add ./cc-dsh-notifier-0.1.4.tgz

Alternative — git install (clones the whole repository, zero config):

dsh plugin --profile web add github:baobaolaodie/cc-dsh-notifier
dsh plugin --profile dsh-tui add github:baobaolaodie/cc-dsh-notifier

GitHub Packages (@baobaolaodie/cc-dsh-notifier) exists as a maintainer convenience channel only: GitHub Packages' npm registry always requires a read:packages token for downloads, even for public packages (verified). Use the tarball or git install instead.

Verified against dsh 0.1.0-rc.6 on Windows 11 (2026-08-16): web and tui profiles, permission/question/waiting-for-input notifications, focus-aware silence, click-to-return, and the tarball install flow.

Verify

npm test

Usage

Claude Code

Start a session and switch away. The system notifies when Claude requests a permission, asks a question, or finishes a turn.

claude
# switch to another window; toasts appear when Claude needs you

DeepSeek Harness

The plugin forwards dsh session events into the same pipeline. Web sessions bind to the browser window; tui sessions bind to the terminal window:

dsh web          # or: dsh --profile web
dsh-tui          # or: dsh --profile dsh-tui

Manual trigger (testing)

node scripts/test.mjs permission-request   # permission-request | ask-user-question | stop | session-start

Toasts are suppressed while the target window is focused, so switch away to observe them.

Configuration

Edit ~/.cc-notifier/config.json (created on install):

Architecture

An event-driven pipeline runs only while sessions are active. Claude Code hooks and the dsh plugin both produce the same normalized payloads; a resident daemon decides whether to notify, and a Python agent shows the toast:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px'}}}%%
flowchart LR
    CC["Claude Code<br/>hooks"] --> NA["notify-agent.mjs<br/>forwarder"]
    DSH["dsh-notifier<br/>plugin · web/tui"] --> NA
    NA -->|"HTTP · localhost"| DM["daemon.mjs<br/>sessions · focus · lifecycle"]
    DM --> TA["toast-agent.py<br/>winrt toast"]
    TA -->|"click"| WIN["session window<br/>SetForegroundWindow · UIA tab"]
    DM --> ST[("state · logs<br/>%LOCALAPPDATA%")]

    classDef client fill:#3B82F6,stroke:#2563EB,color:#fff,stroke-width:2px
    classDef service fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
    classDef data fill:#8B5CF6,stroke:#7C3AED,color:#fff,stroke-width:2px

    class CC,DSH,WIN client
    class NA,DM,TA service
    class ST data

The daemon is single-instance: it wakes on demand, exits after 60 seconds of no sessions, and self-restarts when its code changes. Sessions re-register automatically after a daemon restart.

Project Structure

├── scripts/               # Runtime pipeline
│   ├── notify-agent.mjs   # Hook forwarder (Claude Code)
│   ├── daemon.mjs         # Resident process: sessions, focus, dedup
│   ├── toast-agent.py     # Python winrt toast + click handling
│   └── lib/               # Shared modules, win32 bridge, UIA helpers
├── plugins/
│   └── dsh-notifier/      # dsh bundle plugin (web + tui profiles)
├── test/                  # node:test suite (explicit file list)
├── docs/                  # Installation, usage, troubleshooting (bilingual)
└── package.json           # Zero runtime dependencies

Tech Stack

Deployment

CI runs on GitHub Actions (test × 6 matrix across Node 18/20/22 on Ubuntu and Windows, plus quality, pr-policy, docs-links, and a summary job). See .github/workflows/ci.yml.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-change)
3. Commit with Conventional Commits (feat:, fix:, docs:, …)
4. Open a Pull Request

PRs must pass the full CI suite, including the bilingual documentation mirror check and version consistency checks. See CONTRIBUTING.md.

License

MIT