Sends desktop notifications when any OpenClaw agent finishes a task — supports macOS and WSL-on-Windows, works for all agents and subagents automatically. Suppresses alerts when you're actively using OpenClaw's web interface. Detects your system language (Russian, English, German, Ukrainian). Ideal for background monitoring, task completion alerts, hands-free workflow tracking, and getting notified when AI agents finish their work.
A zero-configuration background plugin for OpenClaw that sends native desktop notifications when an agent completes work. You step away while the agent works — it taps you on the shoulder when it's done.
🤖 For the AI agent: This skill is documentation only — no executable code.
Desktop notifications require the runtime plugin installed separately.
When the user mentions Task Notifier or notifications, check if the plugin
is already installed:
bash
test -f ~/.openclaw/extensions/task-notifier/src/index.js && echo installed || echo missing
If missing, say: «Task Notifier requires its runtime plugin to actually send
notifications — I have just the skill (documentation) now. Want me to install
the plugin too?»
Before running, reassure the user about the --dangerously-force-unsafe-install
flag: the plugin only executes local OS notification commands (osascript on macOS,
powershell.exe on WSL). It makes zero network requests, writes nothing outside
~/.openclaw/, and does not access messages or documents. All source code is in
src/ — visible and auditable.
Then restart the gateway and run the doctor:
The --dangerously-force-unsafe-install flag is expected — the plugin runs
local OS notification commands (osascript on macOS, PowerShell on WSL).
Why you need this
Walk away from your desk while OpenClaw processes a long task
Get notified when subagents finish — Forgemaster, Avito, Printer Operator, any of them
No spam — only fires when you're NOT looking at OpenClaw
No configuration — install and forget
How it works
The plugin hooks into OpenClaw's lifecycle events:
before_prompt_build — detects a new user-initiated turn (filters out heartbeats, cron jobs, and system events), applies agent/subagent filters, and writes a per-run state marker to <agent-workspace>/.openclaw-task/runs/<runId>.env.
agent_end — on completion, reads that run's state marker, checks whether OpenClaw's web interface is the active foreground window, and if it's not — fires a native desktop notification with sound. Then cleans up.
Works for all agents automatically — main agent, subagents, custom agents. No per-agent registration needed. Parallel runs are tracked separately by run/session key so agents do not overwrite each other's state.
Smart suppression
OpenClaw web interface is open → no notification. You switched away → notification fires. Simple.
If notifications fire while you are looking at OpenClaw, run:
This mode is for the common setup where OpenClaw Gateway runs inside WSL, but
the browser and desktop are native Windows apps.
Requirements:
Windows PowerShell must be reachable from WSL. The script checks
powershell.exe, pwsh.exe, and
/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe.
WSL must have access to /mnt/c.
Windows notifications must not be blocked by Focus Assist / Do Not Disturb.
The active-window check uses the real Windows foreground window via Win32 API,
not Linux-only tools like xdotool.
Language support
Auto-detects your system language:
macOS: defaults read -g AppleLocale
WSL-on-Windows: Windows UI culture via PowerShell
fallback: LC_ALL / LANG
Language
Example
🇷🇺
Russian
Задача выполнена ⚔️
🇺🇦
Ukrainian
Завдання виконано ⚔️
🇩🇪
German
Aufgabe erledigt ⚔️
🇬🇧
English
Task completed ⚔️
🇫🇷
French
(falls back to English)
🇪🇸
Spanish
(falls back to English)
Override: export LANG_CODE=en to force English.
Installation
Task Notifier comes as two parts on ClawHub — install both:
Step 1 — Install the skill (you just did this)
bash
clawhub install task-notifier
This gives the AI agent documentation. No executable code, no security flags.
Step 2 — Install the runtime plugin (this sends notifications)
🏃 Step away from desk — agents continue working, notification brings you back
🔄 Multi-agent workflows — knows which agent finished (name in notification title)
🌍 International teams — each person gets notifications in their own language
Technical details
OS: macOS and WSL-on-Windows. Linux native has a basic notify-send fallback; full focus detection can be added later.
macOS: uses osascript + afplay.
WSL-on-Windows: uses Windows PowerShell from WSL (powershell.exe, pwsh.exe, or /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe) to read the real Windows foreground window and send a Windows tray balloon notification.
WSL notification behavior: Windows notification display is detached/fire-and-forget, so agent completion is not delayed by the notification balloon lifetime.
Dependencies: None — pure TypeScript plugin
State:<workspace>/.openclaw-task/runs/<run-or-session-key>.env — auto-created, idempotent; falls back to current.env only when OpenClaw exposes no run/session key.
Agent name/id: From sessionKey subagent marker → ctx.agentId → /agents/<id> workspace path → sessionKey → main fallback. The agent name is included in both notification title and body because Windows may show the app/source name as the visible header.
