Task Notifier 🔔

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):

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

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