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:

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:

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

Then restart the gateway and run the doctor:

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

To revert the runtime install later:

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:

~/.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:

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

Verification

Run the doctor:

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

Send a manual test notification:

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:

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:

export LANG_CODE=en

Configuration

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

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