Task Notifier

Sends macOS desktop notifications when any OpenClaw agent finishes a task — 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 macOS native notifications when an agent completes work. You step away while the agent works — it taps you on the shoulder when it's done.

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), writes a state marker to <agent-workspace>/.openclaw-task/current.env.

2. agent_end — on completion, reads the state marker, checks whether OpenClaw's web interface is the active foreground window, and if it's not — fires a native macOS notification with sound. Then cleans up.

Works for all agents automatically — main agent, subagents, custom agents. No per-agent registration needed. Zero configuration.

Smart suppression

OpenClaw web interface is open → no notification. You switched away → notification fires. Simple.

Language support

Auto-detects your macOS system language (defaults read -g AppleLocale):

	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

Via ClawHub (recommended)

clawhub install task-notifier

Then follow the instructions in the installed SKILL.md to set up the plugin.

Manual install

mkdir -p ~/.openclaw/workspace/plugins/task-notifier
cp src/index.ts ~/.openclaw/workspace/plugins/task-notifier/
cp src/task-notify.sh ~/.openclaw/workspace/plugins/task-notifier/
cp openclaw.plugin.json ~/.openclaw/workspace/plugins/task-notifier/

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "load": {
      "paths": ["/path/to/plugins/task-notifier/index.ts"]
    }
  }
}

Restart:

openclaw gateway restart

How to customise

What	How
Sound	Edit afplay path in src/task-notify.sh
Notification text	Edit l10n() strings in the script
Language override	export LANG_CODE=en
Add a language	Add cases to detect_lang() + l10n() in the script

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 only (uses osascript + afplay)
• Dependencies: None — pure TypeScript plugin
• State: <workspace>/.openclaw-task/ — auto-created, idempotent
• Agent name: From ctx.agentId (portable) → path fallback
• Trigger filter: Ignores heartbeat, cron, systemEvent

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

File	Purpose
src/index.ts	Plugin entry — lifecycle hooks
src/task-notify.sh	macOS notification dispatcher with l10n
openclaw.plugin.json	Plugin manifest for OpenClaw
package.json	npm package metadata
SKILL.md	This file
README.md	GitHub readme
LICENSE	MIT-0