HermesCCNotify：基于 Claude Code Hook 的任务完成通知系统

关键词：Hermes · Claude Code · Hook · Notify · 事件监听

是什么

Claude Code 任务完成后，自动推送通知到 macOS 系统弹窗和飞书 / Telegram / Discord / Slack。

本质是一个 shell 脚本，注册为 Claude Code 的 Stop Hook。Claude 每完成一轮任务，Hook 触发，脚本解析事件 JSON，通过 Hermes Webhook 直投消息通道。

Claude Code 任务完成
  → Stop Hook 触发
    → bridge.sh 解析 JSON
      → macOS 通知（osascript，即时）
      → Hermes Gateway :8644（HMAC 签名 POST）
        → 飞书 / Telegram / Discord / Slack

技术原理

1. Claude Code Hook 机制

Claude Code v2.x 支持在生命周期事件上执行 shell 命令。配置文件 ~/.claude/settings.json：

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "bash /path/to/bridge.sh",
        "timeout": 5
      }]
    }]
  }
}

Stop 事件触发时，Claude Code 将当前会话上下文以 JSON 写入 stdin：

{
  "hook_event_name": "Stop",
  "session_id": "uuid",
  "cwd": "/path/to/project",
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "last_user_message": "用户最后一条消息",
  "last_assistant_message": "Claude 的回复内容",
  "usage": { "input_tokens": 15420, "output_tokens": 3847 }
}

2. bridge.sh 处理流程

# 解析 stdin JSON → 提取关键字段
PAYLOAD=$(cat | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(json.dumps({
    'project': data['cwd'].split('/')[-1],
    'model': data['model'],
    'last_user_message': data.get('last_user_message', '')[:200],
    'last_assistant_message': data.get('last_assistant_message', '')[:300],
    ...
}))
")

# macOS 系统通知
osascript -e "display notification \"...\" with title \"Claude Code · ${PROJECT}\""

# POST 到 Hermes Webhook
curl -s --noproxy '*' \
    -X POST "${HERMES_WEBHOOK}" \
    -H "X-Hub-Signature-256: $(hmac_sign "${PAYLOAD}")" \
    -d "${PAYLOAD}"

关键约束：Hook 超时 5 秒，bridge.sh 必须在 2 秒内完成。不做重试、不做复杂格式化，轻量 fire-and-forget。

3. Hermes Webhook 投递

Hermes Gateway 监听 :8644，接收 HMAC-SHA256 签名的 POST 请求。配置为 --deliver-only 模式——直接渲染模板投递到目标通道，不经过 Agent，零 LLM 成本。

hermes webhook subscribe hermesccnotify \
  --prompt "🤖 Claude Code · {project} ..." \
  --deliver feishu \
  --deliver-only

模板变量 {project} {model} {last_user_message} 等由 POST body 中的 JSON 字段自动替换。

4. 安装

git clone https://github.com/ssssmy/HermesCCNotify.git
cd HermesCCNotify
./install.sh --global

install.sh 读取 ~/.claude/settings.json，在 hooks.Stop 中追加 bridge.sh 条目。支持 --project DIR 项目级安装、--webhook URL 自定义 Webhook。

5. 卸载

./uninstall.sh --global

移除 hook 条目，清理 ~/.hermesccnotify/ 运行时目录。

核心设计决策

决策	选择	原因
通知通道	macOS + Hermes Webhook 双通道	macOS 即时可见，Webhook 推手机
投递模式	`--deliver-only`	不走 Agent，零延迟零 LLM 成本
触发方式	Hook 事件驱动	不轮询，毫秒级响应
HMAC 签名	原始密钥字节	避免 hex 编解码错误
代理处理	`curl --noproxy '*'`	Claude Code 环境变量含代理，避免 localhost 走代理

踩坑记录

HMAC 签名错误：对密钥做了多余的 bytes.fromhex(secret.encode().hex())，实际应直接用 secret.encode()。导致 Gateway 验签失败断开连接。

代理变量泄漏：Claude Code 配置中的 http_proxy 被子进程继承，curl 将 localhost:8644 也走代理导致无法连接。修复方式 --noproxy '*'，仅影响 curl 自身。

Hook 超时：Claude Code Hook 默认超时 5 秒，bridge.sh 耗时必须控制在 2 秒内，所有重逻辑下沉到 Hermes 侧。

代码量

bridge.sh — 115 行
install.sh — 160 行
依赖：bash + python3 + curl（macOS 全部自带）
Hook 执行时间：< 2 秒
通知延迟：macOS 即时，飞书 < 1 秒

仓库

https://github.com/ssssmy/HermesCCNotify

2026-05-01 · Claude Code · Hook · Hermes · Notify