Task Notifier

Task Notifier 🔔

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:

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?»

If they agree, run:

openclaw plugins install clawhub:task-notifier --dangerously-force-unsafe-install --force

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:

bash ~/.openclaw/extensions/task-notifier/scripts/doctor.sh

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:

1. 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.

2. 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:

~/.openclaw/extensions/task-notifier/src/task-notify.sh probe

Then add a distinctive active-window title fragment:

export TASK_NOTIFIER_ACTIVE_MATCH="openclaw|localhost:18789|127.0.0.1:18789|my openclaw window title"

WSL-on-Windows notes

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

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)

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)

openclaw plugins install clawhub:task-notifier --dangerously-force-unsafe-install

The --dangerously-force-unsafe-install flag is expected — the plugin calls local OS notification APIs (osascript on macOS, PowerShell on WSL).

💡 The AI agent will detect a missing plugin and offer to install it for you. Just say yes.

What the plugin install does:

1. Downloads and installs the runtime code to ~/.openclaw/extensions/task-notifier/
2. Enables the plugin and grants allowConversationAccess hook permission
3. Adds task-notifier to plugins.allow

Step 3 — Restart the gateway and verify

openclaw gateway restart
bash ~/.openclaw/extensions/task-notifier/scripts/doctor.sh

Send a test notification:

AGENT_NAME="Test" STATE_DIR=/tmp/task-notifier-test \
  ~/.openclaw/extensions/task-notifier/src/task-notify.sh done "Hello world ⚔️"

How to customise

Use cases

• 🎮 Gaming while agents work — get notified when Forgemaster finishes generating
• 📊 Monitoring batch processing — Avito listings, printer jobs, data analysis
• 🏃 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.
• Trigger filter: Ignores heartbeat, cron, systemEvent.
• Agent filters: TASK_NOTIFIER_NOTIFY_MAIN, TASK_NOTIFIER_NOTIFY_SUBAGENTS, TASK_NOTIFIER_INCLUDE_AGENTS, TASK_NOTIFIER_EXCLUDE_AGENTS.
• Completion hook: Uses agent_end.

Keywords (for search)

task notification, agent completion, macOS alerts, desktop notification, OpenClaw plugin, background monitoring, task done alert, work complete, AI agent notifier, productivity tool, multi-agent support, subagent notifications, sound alert, smart suppression, hands-free workflow, auto-language, russian notifications, german notifications

Files