Agent Notify

在 AI Agent（如 Claude Code、Codex）逐渐融入日常开发工作流的今天，长时间运行的任务或需要人工授权的步骤往往会让开发者陷入“盲目等待”或“频繁切换窗口检查”的困境。Agent Notify 是一个专为 AI Agent 设计的通知配置工具，能够将关键事件实时推送到你的飞书、企业微信或系统通知中心，让你随时掌握 Agent 动态。

核心亮点：多通道、全覆盖

1. 多渠道即时推送

• 飞书通知：支持一键扫码绑定，通过飞书机器人消息推送，方便在手机端随时查看。
• 企业微信通知：支持通过群机器人 Webhook 推送，适合企业内部协作场景。
• 系统通知：原生支持 macOS、Linux、Windows 系统通知栏，无需额外打开应用即可感知状态。

2. 精细化的事件订阅

针对不同 Agent 的能力，支持多种关键事件监听：

• Claude Code：通过 ~/.claude/settings.json 的 hooks 订阅全部四个事件。
• Codex：通过 ~/.codex/hooks.json 订阅 PermissionRequest 与 Stop，映射为授权与完成通知。

3. 零维护自动化

• 自动安装与更新：首次运行 npx agent-notify 即自动下载对应平台二进制文件至 ~/.agent-notify/。后续运行会自动检查版本，落后则更新，否则直接执行。
• 路径隔离：Launcher 不修改全局 PATH，始终使用绝对路径执行，避免环境冲突。

二、 快速开始指南

1. 一键启动

在终端运行：

npx agent-notify

首次运行将引导你完成配置向导，包括选择通知渠道、绑定账号等。

2. 配置 Agent Hooks

对于 Claude Code：
工具会自动写入 ~/.claude/settings.json，添加如下 hooks 配置：

{
  "hooks": {
    "PermissionRequest": "agent-notify handle-claude-hook",
    "Notification": "agent-notify handle-claude-hook",
    "Stop": "agent-notify handle-claude-hook",
    "PostToolUseFailure": "agent-notify handle-claude-hook"
  }
}

对于 Codex：
工具会自动写入 ~/.codex/hooks.json：

{
  "hooks": {
    "PermissionRequest": "agent-notify handle-codex-hook",
    "Stop": "agent-notify handle-codex-hook"
  }
}

注意：首次配置 Codex 后，需在 Codex 交互界面运行 /hooks 命令完成信任审核。

3. 企业微信机器人配置（可选）

若选择企业微信通知，需先获取 Webhook URL：

1. 创建单人通知群：在企业微信发起群聊，拉入同事后将其移出，形成单人群。
2. 添加机器人：进入「群设置」->「消息推送」->「添加」->「自定义消息推送」。
3. 获取地址：复制生成的 Webhook 地址（格式：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx）。
4. 绑定配置：在 npx agent-notify 配置向导中粘贴该地址。

配置文件说明

• Agent Notify 配置：位于 ~/.agent-notify/config.yaml，存储通知渠道密钥及偏好设置。
• Claude Code 配置：位于 ~/.claude/settings.json。
• Codex 配置：位于 ~/.codex/hooks.json。

适用场景

• 长时任务监控：当 Agent 执行耗时较长的代码生成或重构任务时，你可以安心处理其他事务，待收到 run_completed 通知后再回来检查结果。
• 远程授权响应：当 Agent 需要执行敏感命令触发 permission_required 时，飞书/企微通知能让你在手机端迅速知晓并回到电脑前授权，避免任务阻塞。
• 异常即时感知：任务失败 (run_failed) 时立即收到提醒，便于快速排查错误日志。