agent-notifier

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Notifier Skill

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

面向AI代码Agent的确定性、基于钩子的通知工具。再也不会错过Agent需要输入或完成任务的时刻。

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.

基于大语言模型的“完成时播放声音”提示词并不可靠——上下文压缩会丢失这些提示，且模型对“完成”的判断不一致。本Skill使用各平台的钩子系统确保触发通知。

Prerequisites

前置要求

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

Python 3（仅使用标准库，无外部依赖）
至少一个受支持的AI Agent平台

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`

平台	钩子事件
Claude Code	`Notification` (idle_prompt, permission_prompt)
GitHub Copilot CLI	`sessionEnd` , `postToolUse`
Cursor	`stop` , `afterFileEdit`
Codex	`agent-turn-complete`
Aider	`--notifications-command`

Quick Start

快速开始

bash

undefined

bash

undefined

Interactive setup — detects platforms, configures channels, installs hooks

python3 skills/agent-notifier/setup.py

undefined

python3 skills/agent-notifier/setup.py

undefined

Copilot CLI Users

Copilot CLI 用户

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

Copilot CLI 从项目的

.github/hooks/

目录加载钩子（不支持全局钩子）。在每个需要通知的项目中创建钩子文件：

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

Manual Usage

手动使用

bash

undefined

bash

undefined

Test with simulated Claude Code event

echo '{"notification_type":"idle_prompt","message":"Waiting for input"}' | python3 skills/agent-notifier/notify.py

Test with command-line args (Aider style)

python3 skills/agent-notifier/notify.py "Task completed"

undefined

python3 skills/agent-notifier/notify.py "Task completed"

undefined

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

渠道	默认状态	要求
声音	已启用	macOS ( `afplay` ) 或 Linux ( `paplay` / `aplay` )
macOS 通知	已启用	仅支持macOS
Telegram	已禁用	Bot令牌 + 聊天ID
邮件	已禁用	SMTP凭据
Slack	已禁用	传入Webhook URL
Discord	已禁用	Webhook URL

Configuration

配置

Config file is searched in order:

```
~/.claude/notify-config.json
```

skills/agent-notifier/notify-config.json

(template)

Run

python3 skills/agent-notifier/setup.py

to configure interactively, or edit the JSON directly.

配置文件的搜索顺序：

```
~/.claude/notify-config.json
```

skills/agent-notifier/notify-config.json

（模板）

运行

python3 skills/agent-notifier/setup.py

进行交互式配置，或直接编辑JSON文件。

Output

输出

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

通知会并发发送至所有已启用的渠道。单个渠道的失败会记录到stderr，但不会影响其他渠道。