agent-notifier

Multi-platform, multi-channel notification skill for AI code agents. Sends notifications (sound, macOS alert, Telegram, Email, Slack, Discord, DingTalk) when the agent needs user interaction or completes a task. Supports Claude Code, GitHub Copilot CLI, Cursor, Codex, Aider, and OpenCode.

11 stars

bycrossoverJie

View on GitHub Installation ↓

Best use case

agent-notifier is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using agent-notifier should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/agent-notifier/SKILL.md --create-dirs "https://raw.githubusercontent.com/crossoverJie/skills/main/skills/agent-notifier/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/agent-notifier/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How agent-notifier Compares

Feature / Agent	agent-notifier	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

Related Guides

Best AI Skills for Claude

Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.

SKILL.md Source

# 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

```bash
# 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:

```bash
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:

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

## Manual Usage

```bash
# 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.

Related Skills

We are still matching the closest adjacent skills for this page. In the meantime, continue through the full directory.