dsh-task-notify

Lifecycle notification layer for AI coding agents, currently supporting DeepSeek Harness.

AI coding agents increasingly run long-lived, autonomous tasks: a turn can take minutes, and the human has usually moved to another window. This project adds the missing notification layer on top of an agent's task lifecycle, so the moment an agent completes, fails, settles a background job, or starts waiting for a human (approval / plan review / question), you get an in-page toast, an OS-level desktop notification, and an optional sound.

Inspired by Codex's desktop-notification UX — not a Codex integration. Not affiliated with or sponsored by OpenAI. Today the project ships as a DeepSeek Harness (DSH) plugin. Its lifecycle-detection core is host-agnostic and is designed to grow into adapters for other coding agents.

Why this exists

Long-running agent tasks invert the normal attention model: instead of watching a terminal, users submit a task and switch away. UI-only status indicators (a spinner in a background tab) fail exactly when they matter most — when the user is not looking. dsh-task-notify turns lifecycle transitions into interruptible, OS-level signals, closing the feedback loop between an autonomous agent and a distracted human.

Demo

Placeholder — replace with short recordings (GIF or MP4, ~10–30 s each). See docs/demo-guide.md.

Turn completed	Approval required	Background job failed

Features

• Turn completion — fires when an agent turn (thinking or tool use) finishes.
• Background job — fires when a background command or subagent job settles (completed, failed, killed).
• Review needed — fires when a running task waits for approval, plan review, or a question answer.
• Failure — fires when an agent turn errors or a background job fails / is killed.
• Three channels — OS-level browser notification, in-page toast, optional two-tone beep.
• Per-event config — every trigger and channel can be toggled independently.

Install

Prerequisites: Node.js and pnpm.

# npm (recommended)
dsh plugin --profile web add @ltao0829/dsh-task-notify

# or from Git
dsh plugin --profile web add git+https://github.com/ltao0829/dsh-task-notify.git

Restart dsh web and refresh the page. On the first click/keypress the browser asks for notification permission — allow it to receive desktop notifications.

Configuration

The settings card lives in the plugin section of DSH's settings UI. Values are stored locally in localStorage (dsh.taskNotify.v1):

Toggle	Default	Meaning
Enable reminders	on	master switch
Turn completion	on	an agent turn finishes
Background job	on	a background command / subagent job settles
Review needed	on	a running task waits for approval / plan review / question
Failure	on	a turn errors or a job fails / is killed
Browser notification	on	also send an OS-level notification (needs permission)
Sound	off	also play a short beep

Architecture

              coding agent
                   │
                   ▼
     host adapter  (DeepSeek Harness today;
                   Claude Code / Codex / OpenCode later)
                   │
                   ▼
   sessions snapshot (N-1 vs N)
                   │
                   ▼
   lifecycle detector  ──►  events: turn | job | review | failure
                   │
                   ▼
   notification dispatcher
         │          │          │
         ▼          ▼          ▼
       OS          toast      sound
   notification

The detector (src/detect.ts) is a pure function: a snapshot goes in, lifecycle events come out. It knows nothing about DSH or the DOM, which is what makes additional coding-agent adapters a matter of implementing a new snapshot provider rather than rewriting the notification core.

• The first snapshot only establishes a baseline — refreshing the page never replays history.
• src/detect.ts is host-agnostic (plain data in / plain data out) and is unit-tested in isolation.

Project layout

src/index.ts                         host half — registers the settings section
src/detect.ts                        pure lifecycle detector (snapshot diff)
src/client/index.ts                  browser half — watcher + failure watcher
src/client/notify.ts                 toast / OS notification / sound
src/client/settings.ts               localStorage-backed settings store
src/client/TaskNotifySettingsCard.tsx settings UI card
tests/*.spec.ts                      detector, settings, notification, lifecycle tests

Security & Privacy

• No external server, no cloud backend.
• No telemetry, no analytics, no tracking.
• No API key required.
• Notifications are generated locally in the browser.
• Settings are stored locally in localStorage only.
• The plugin does not upload or exfiltrate conversation content.

The plugin runs with the permissions of your DSH process, like any other DSH plugin.

Roadmap

Current

• Turn-completion notifications
• Background-job notifications
• Approval / plan-review / question notifications
• Failure notifications
• OS notification + toast + sound
• npm distribution (@ltao0829/dsh-task-notify)
• CI/CD (typecheck + test + build + pack dry-run)

Near term

• npm download metrics / adoption tracking
• Cross-platform notification backend
• Notification customization
• Better test coverage

Long term

• Agent-agnostic lifecycle API
• Additional coding-agent adapters (Claude Code, Codex, OpenCode, …)
• Reusable notification core

Related projects

• dsh-launcher — one-click launcher for DeepSeek Harness Web.

Together these form a small suite of tooling for AI coding-agent workflows.

Contributing

See CONTRIBUTING.md.

Development

pnpm install
pnpm run typecheck
pnpm test
pnpm run build

License

BSD-3-Clause