agent-notify

一个面向 AI Agent 的通知配置工具。支持将 Claude Code、Codex 等 Agent 的事件通知推送到飞书和系统通知。

功能特性

• 🖥️ 系统通知 - 支持 macOS 原生通知
• 📱 飞书通知 - 支持飞书机器人消息推送
• 🔔 事件订阅 - 支持多种事件类型：授权请求、等待输入、任务完成、任务失败
• 🔄 自动安装 - 自动配置 Claude Code / Codex hooks
• 📦 NPX 一键安装 - 无需手动下载，一条命令完成安装

安装

通过 NPX 运行（推荐）

npx agent-notify

首次运行会从 GitHub Releases 下载当前 npm 包版本对应平台的二进制文件，并安装到：

• macOS / Linux: ~/.agent-notify/agent-notify
• Windows: ~/.agent-notify/agent-notify.exe

之后每次运行 npx agent-notify 时都会检查本地二进制版本：

• 本地不存在：自动下载
• 本地版本落后：自动更新
• 本地版本不落后：直接运行本地二进制

launcher 不会持久修改你的 PATH，而是始终用绝对路径执行已安装的真实二进制。

支持的平台

• macOS amd64
• macOS arm64
• Linux amd64
• Linux arm64
• Windows amd64
• Windows arm64

通过 npm 全局安装

npm install -g agent-notify
agent-notify

全局安装 npm 包后，运行方式与 npx agent-notify 一致：launcher 仍会把真实二进制安装到 ~/.agent-notify/ 并按版本检查后执行。

手动下载

从 GitHub Releases 下载对应平台的二进制文件。

快速开始

通过 launcher 使用

NPX

npx agent-notify
npx agent-notify init
npx agent-notify test system
npx agent-notify test feishu
npx agent-notify doctor

npm 全局安装后的 launcher 入口

npm install -g agent-notify
agent-notify
agent-notify init
agent-notify test system
agent-notify test feishu
agent-notify doctor

无论是 npx agent-notify 还是全局安装后的 agent-notify，入口仍然是 launcher；它会把真实二进制放在 ~/.agent-notify/ 下并按版本检查后执行。

通过手动下载的二进制使用

如果你下载了 release 二进制，并直接执行该文件，则可以使用：

./agent-notify
./agent-notify init
./agent-notify test system
./agent-notify test feishu
./agent-notify doctor

按提示选择：

1. 选择要配置的 Agent（Claude Code / Codex）
2. 选择通知渠道（系统通知默认选中）
3. 选择要接收通知的事件类型

支持的事件

事件	说明
permission_required	Agent 需要授权（如执行命令）
input_required	Agent 等待用户输入
run_completed	任务执行完成
run_failed	任务执行失败

配置文件

配置文件位于 ~/.agent-notify/config.yaml

version: 1
agent:
  claude_code:
    enabled: true
    install_scope: user
  codex:
    enabled: false
    install_scope: user
notify:
  system:
    enabled: true
    events:
      - permission_required
      - input_required
      - run_completed
      - run_failed
  feishu:
    enabled: false
    events: []
behavior:
  dedupe_seconds: 60
  send_timeout_seconds: 5
  locale: zh-CN

命令参考

launcher 方式

npx agent-notify              # 通过 npx 进入交互式主菜单
npx agent-notify init         # 通过 npx 初始化配置
npx agent-notify test system  # 通过 npx 测试系统通知
npx agent-notify test feishu  # 通过 npx 测试飞书通知
npx agent-notify doctor       # 通过 npx 做环境诊断
npx agent-notify --help       # 通过 npx 查看帮助

agent-notify                  # npm 全局安装后的 launcher 入口
agent-notify init
agent-notify test system
agent-notify test feishu
agent-notify doctor
agent-notify --help

手动下载的二进制方式

./agent-notify              # 直接执行下载后的二进制
./agent-notify init
./agent-notify test system
./agent-notify test feishu
./agent-notify doctor
./agent-notify --help

飞书配置

首次使用飞书通知时，会自动引导你完成飞书 CLI 的初始化：

1. 扫码登录
2. 选择要使用的机器人

飞书的通知目标为机器人的所有者；

开发

# 运行测试
go test ./...

# 本地开发运行
go run ./cmd/agent-notify

# 构建
go build -o agent-notify ./cmd/agent-notify

License

MIT