agent-notifier

Agent Notifier Skill

Deterministic, hook-driven notifications for AI code agents. Never miss when your agent needs input or finishes a task.

Why

LLM-based "play a sound when done" prompts are unreliable — context compression drops them, and the model's judgement of "done" is inconsistent. This skill uses each platform's Hooks system for guaranteed triggering.

Prerequisites

• Python 3 (standard library only, no external dependencies)
• At least one supported AI agent platform

Supported Platforms

Platform	Hook Event
Claude Code	Notification (idle_prompt, permission_prompt)
GitHub Copilot CLI	sessionEnd, postToolUse
Cursor	stop, afterFileEdit
Codex	agent-turn-complete
Aider	--notifications-command
OpenCode	session.idle (plugin)

Quick Start

# Interactive setup — detects platforms, configures channels, installs hooks
python3 skills/agent-notifier/setup.py

Copilot CLI Users

Copilot CLI loads hooks from the project's .github/hooks/ directory (no global hook support). Create the hook file in each project where you want notifications:

mkdir -p .github/hooks
cat > .github/hooks/agent-notifier.json << 'EOF'
{
  "version": 1,
  "hooks": {
    "sessionEnd": [
      {"type": "command", "bash": "python3 $HOME/.claude/skills/agent-notifier/notify.py"}
    ],
    "postToolUse": [
      {"type": "command", "bash": "python3 $HOME/.claude/skills/agent-notifier/notify.py"}
    ]
  }
}
EOF

OpenCode Users

OpenCode uses a JavaScript plugin system. Copy the plugin to your plugins directory:

mkdir -p ~/.config/opencode/plugins
cp skills/agent-notifier/opencode-plugin.js ~/.config/opencode/plugins/agent-notifier.js

Manual Usage

# Test with simulated Claude Code event
echo '{"notification_type":"idle_prompt","message":"Waiting for input"}' | python3 skills/agent-notifier/notify.py

# Test with simulated OpenCode event
echo '{"platform":"opencode","event_type":"session.idle","message":"Session completed"}' | python3 skills/agent-notifier/notify.py

# Test with command-line args (Aider style)
python3 skills/agent-notifier/notify.py "Task completed"

Notification Channels

Channel	Default	Requirements
Sound	Enabled	macOS (afplay) or Linux (paplay/aplay)
macOS Notification	Enabled	macOS only
Telegram	Disabled	Bot token + Chat ID
Email	Disabled	SMTP credentials
Slack	Disabled	Incoming Webhook URL
Discord	Disabled	Webhook URL
DingTalk	Disabled	Webhook URL + optional Secret

Configuration

Config file is searched in order:

1. ~/.claude/notify-config.json
2. skills/agent-notifier/notify-config.json (template)

Run python3 skills/agent-notifier/setup.py to configure interactively, or edit the JSON directly.

Output

Notifications are sent concurrently to all enabled channels. Individual channel failures are logged to stderr without affecting other channels.