Task Notifier#

Task Notifier is an OpenClaw notification helper. When the runtime plugin is installed, it sends a native desktop notification after an OpenClaw agent finishes a user-initiated task, unless OpenClaw is currently the active foreground window.

For the AI agent: this skill is documentation and operating guidance. The actual desktop notification behavior requires the separate runtime plugin package.

When to use this skill#

Use this skill when the user explicitly asks to install, set up, configure, verify, debug, update, or uninstall Task Notifier, or explicitly asks for desktop notifications when OpenClaw agents finish work.

Do not treat generic mentions of notifications, alerts, reminders, desktop settings, or operating-system notification behavior as permission to install or configure Task Notifier. In those cases, answer the user's actual question first and only discuss Task Notifier if it is clearly relevant.

Safe setup workflow#

If the user asks to set up or check Task Notifier, first check whether the runtime plugin is installed:

bash

test -f ~/.openclaw/extensions/task-notifier/src/index.js && echo installed || echo missing

If it is missing, explain plainly:

Task Notifier needs its runtime plugin to send desktop notifications. The skill only documents the workflow; the plugin is the code that registers OpenClaw lifecycle hooks and calls local OS notification commands.

Before installing, get explicit user confirmation. Tell the user what the install changes:

• downloads the runtime plugin to ~/.openclaw/extensions/task-notifier/;
• enables task-notifier in OpenClaw plugin config;
• adds it to plugins.allow;
• grants lifecycle hook access with allowConversationAccess;
• requires --dangerously-force-unsafe-install because the plugin intentionally runs local notification commands.

The flag is a real security decision, not a cosmetic warning. The runtime plugin is designed to use local OS notification tools ( osascript on macOS, PowerShell on WSL-on-Windows, and notify-send on Linux fallback), inspect the active foreground window title for suppression, and write small per-run state files under the active workspace's .openclaw-task/ directory. The runtime itself does not need network access for notifications, but installing or updating from ClawHub uses network access.

Privacy note: allowConversationAccess lets the runtime receive OpenClaw lifecycle hook context for conversations and agent turns. Task Notifier uses that context only to decide when a user-initiated agent run started/ended, identify the agent name, and avoid heartbeat/cron/system-event noise. Do not install it unless the user explicitly accepts persistent lifecycle hook access across agents.

After explicit approval, install the runtime plugin:

bash

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

Then restart the gateway and run the doctor:

bash

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

To revert the runtime install later:

bash

openclaw plugins disable task-notifier || true
openclaw plugins uninstall task-notifier || true
openclaw gateway restart

How it works#

The runtime plugin registers OpenClaw lifecycle hooks:

1. before_prompt_build detects a new user-initiated turn, filters out heartbeat, cron, and system-event turns, applies agent filters, and writes a per-run marker to <agent-workspace>/.openclaw-task/runs/<runId>.env.

2. agent_end reads that run marker, checks whether OpenClaw is the active foreground window, sends a native desktop notification when OpenClaw is not active, and then cleans up the marker.

The plugin tracks runs separately by run/session key so parallel agents do not overwrite each other. It works for the main agent and subagents unless filtered by environment variables.

Smart suppression#

If OpenClaw's web interface is the active foreground window, the runtime suppresses the notification. If the user has switched away, it sends the notification.

Probe the current foreground-window detection:

bash

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

If notifications fire while the user is looking at OpenClaw, configure a distinctive active-window title fragment:

bash

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

Verification#

Run the doctor:

bash

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

Send a manual test notification:

bash

AGENT_NAME="Test" STATE_DIR=/tmp/task-notifier-test STATE_FILE=/tmp/task-notifier-test/runs/manual.env \
  ~/.openclaw/extensions/task-notifier/src/task-notify.sh start

AGENT_NAME="Test" STATE_DIR=/tmp/task-notifier-test STATE_FILE=/tmp/task-notifier-test/runs/manual.env \
  ~/.openclaw/extensions/task-notifier/src/task-notify.sh done "Task Notifier test"

If OpenClaw is active, the done command may report notification suppressed: OpenClaw is active. To test the notification path deliberately, set a non-matching active-window expression for that one command:

bash

TASK_NOTIFIER_ACTIVE_MATCH="__never_match_openclaw__" \
AGENT_NAME="Test" STATE_DIR=/tmp/task-notifier-test STATE_FILE=/tmp/task-notifier-test/runs/manual.env \
  ~/.openclaw/extensions/task-notifier/src/task-notify.sh done "Task Notifier test"

WSL-on-Windows notes#

This mode is for setups 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 or 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 the system language:

• macOS: defaults read -g AppleLocale
• WSL-on-Windows: Windows UI culture via PowerShell
• fallback: LC_ALL / LANG

Supported notification languages:

• Russian: Задача выполнена
• Ukrainian: Завдання виконано
• German: Aufgabe erledigt
• English: Task completed

Override language detection with:

bash

export LANG_CODE=en

Configuration#

WhatHowLanguage overrideexport LANG_CODE=enActive-window matching`export TASK_NOTIFIER_ACTIVE_MATCH="openclawDisable main agent notificationsexport TASK_NOTIFIER_NOTIFY_MAIN=falseDisable subagent notificationsexport TASK_NOTIFIER_NOTIFY_SUBAGENTS=falseNotify only selected agentsexport TASK_NOTIFIER_INCLUDE_AGENTS="main,forgemaster"Exclude selected agentsexport TASK_NOTIFIER_EXCLUDE_AGENTS="noisy-agent,avito"Hide agent name in notification bodyexport TASK_NOTIFIER_AGENT_IN_BODY=falseStale state cleanupexport TASK_NOTIFIER_STATE_TTL_HOURS=24; set 0 to disable

Agent filters match raw agent id or display name after simple normalization.

Use cases#

• Step away from the desk while OpenClaw handles a long task.
• Get notified when subagents finish background work.
• Monitor batch processing or multi-agent workflows without staring at the web UI.
• Reduce notification spam by suppressing alerts while OpenClaw is already active.

Technical details#

• OS support: macOS, WSL-on-Windows, and basic Linux fallback.
• macOS notifications use osascript and afplay.
• WSL-on-Windows notifications use Windows PowerShell to inspect the foreground window and send a tray notification.
• Linux fallback uses notify-send when available.
• Runtime state lives in <workspace>/.openclaw-task/runs/<run-or-session-key>.env and is cleaned up after completion.
• Agent name/id resolution uses session metadata, agent id, workspace path, and IDENTITY.md fallback for the main agent.
• Trigger filter ignores heartbeat, cron, and system events.
• Completion hook: agent_end.

Files in the runtime package#

FilePurposesrc/index.jsRuntime plugin entry and lifecycle hookssrc/index.tsTypeScript source for the runtime pluginsrc/task-notify.shCross-platform notification dispatcherscripts/install-plugin.shInstaller/configurator helperscripts/doctor.shPlatform, config, hook, and focus diagnostic helperopenclaw.plugin.jsonPlugin manifest for OpenClawpackage.jsonnpm package metadataSKILL.mdAgent-facing documentationREADME.mdHuman-facing readmeLICENSEMIT-0

Keywords#

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