cc-notify-hooks

cc-notify-hooks

Claude Code 与 Codex CLI 的分级推送通知系统。支持 11 个通知渠道，可作为插件或独立脚本使用，两边共享同一份配置。

为什么需要分级通知？

Claude Code 和 Codex CLI 任务常常需要几秒到几十分钟不等。你不会一直盯着终端，但又需要在合适的时候回来操作。

cc-notify-hooks 将通知分为两级：

短通知（秒级） — 你可能只是切到了浏览器或聊天窗口。系统通知、手机推送这类即时触达的渠道会在几秒内提醒你"Claude 需要你"。如果你看到通知并回来操作了，后续推送自动取消——不会再打扰你。

长通知（分钟级） — 你可能离开了电脑、在开会、甚至不在手机旁。企业微信群、飞书群、Slack 频道这类团队/异步渠道会在几分钟后兜底通知。即使你错过了短通知，最终也能从工作沟通工具里看到任务状态。

核心机制：每次推送前检查用户是否已响应（pending 文件是否还在）。用户一旦回来操作，所有排队中的推送自动作废。短通知解决了问题，长通知就不会再发。

支持的渠道

短通知渠道（即时触达）

适合切屏、短暂离开的场景。

渠道	默认延迟	说明
macOS	3s	零配置，系统原生通知
Telegram	5s	Bot 消息，手机即时推送
Bark	15s	iOS / macOS / Android 推送
Pushover	15s	跨平台推送服务
ntfy	15s	开源推送，支持自建
Gotify	15s	自建推送服务

长通知渠道（异步兜底）

适合离开电脑、开会、或需要团队可见的场景。

渠道	默认延迟	说明
企业微信	5min	群机器人 Webhook
飞书	5min	群机器人 Webhook
钉钉	5min	群机器人 Webhook
Slack	5min	Incoming Webhook
Discord	5min	Channel Webhook

每个渠道的延迟可独立调整。只启用你需要的渠道，其余自动跳过。

工作原理

Claude Code / Codex CLI 事件
    │
    ▼
notify.sh ── 清除旧 pending → 创建新 pending
    │
    │  ┌── 短通知 ──────────────────────────────────┐
    ├─ │ 3s  → pending 还在？ → macOS 系统通知      │
    ├─ │ 5s  → pending 还在？ → Telegram             │
    ├─ │ 15s → pending 还在？ → Bark / ntfy / ...    │
    │  └────────────────────────────────────────────┘
    │  ┌── 长通知 ──────────────────────────────────┐
    └─ │ 5m  → pending 还在？ → 企微 / 飞书 / Slack │
       └────────────────────────────────────────────┘

用户回来操作（发消息 / 点权限按钮）
    └─→ clear_pending.sh → 清除 pending → 后续推送全部取消
         （短通知解决了，长通知就不发了）

安装

依赖

• jq — 解析 JSON（brew install jq / apt install jq）
• curl — 发送推送（通常已预装）

方式一：Claude Code Marketplace（推荐 Claude 用户）

在 Claude Code 中执行：

/plugin marketplace add MarioZZJ/cc-notify-hooks
/plugin install cc-notify-hooks@cc-notify-hooks

安装后运行 /reload-plugins 刷新，然后执行 /cc-notify-hooks:config 启动交互式配置向导（见下方配置章节）。

方式二：Codex CLI Marketplace（推荐 Codex 用户）

仓库根目录的 .codex-plugin/plugin.json 与 .agents/plugins/marketplace.json 即为 Codex 插件清单。可以将本仓库克隆到 ~/plugins/cc-notify-hooks/，然后在 ~/.agents/plugins/marketplace.json 添加：

{
  "name": "cc-notify-hooks",
  "source": {"source": "local", "path": "./plugins/cc-notify-hooks"},
  "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
  "category": "Productivity"
}

启用 hooks（必需，Codex 默认关闭）：在 ~/.codex/config.toml 添加：

[features]
codex_hooks = true

之后在 Codex 中 /plugin 安装即可。

注意：Codex 的 hook 命令运行目录是当前会话 cwd，不是插件根目录。.codex-plugin/plugin.json 只负责把 hooks/codex-hooks.json 作为生命周期配置打包进去；hook 命令不能写成 ./scripts/...，否则在普通项目里会找不到脚本并报 No such file or directory。本插件的 Codex hook 会从 ~/.codex/plugins/cache/*/cc-notify-hooks/*/ 自动定位安装副本。

方式三：本地插件模式

git clone https://github.com/MarioZZJ/cc-notify-hooks.git

# Claude Code
claude --plugin-dir ./cc-notify-hooks

# Codex CLI: 见上文 Codex Marketplace 方式

方式四：独立安装（无需插件）

git clone https://github.com/MarioZZJ/cc-notify-hooks.git
cd cc-notify-hooks
bash install.sh                  # 交互式选择 Claude Code / Codex
bash install.sh claude           # 直接装到 Claude Code
bash install.sh codex            # 直接装到 Codex CLI

安装脚本会交互式引导你选择渠道、输入凭证，自动生成配置：

• Claude 分支：写 ~/.claude/hooks/notify.json，合并 hooks 到 ~/.claude/settings.json
• Codex 分支：写 ~/.codex/cc-notify-hooks/notify.json，合并 hooks 到 ~/.codex/hooks.json，提示你启用 codex_hooks

Claude 安装后运行 /reload-plugins 刷新；Codex 安装后重启 Codex 进程。

验证

bash test_notify.sh              # 测试所有已启用渠道
bash test_notify.sh bark         # 测试单个渠道
bash test_notify.sh list         # 查看已启用渠道及延迟
bash test_notify.sh hook         # 模拟 Claude Code hook 流程
bash test_notify.sh codex        # 模拟 Codex CLI PermissionRequest 事件
bash test_notify.sh codex-plugin-hooks  # 验证 Codex 插件 hook 路径解析
bash test_notify.sh render       # 验证通知内容模板

配置

方式一：交互式配置（推荐）

在 Claude Code 中运行：

/cc-notify-hooks:config

配置向导会引导你：

1. 选择要启用的短通知渠道（macOS、Telegram、Bark 等）
2. 选择要启用的长通知渠道（企业微信、飞书、Slack 等）
3. 逐个输入渠道凭证，附带获取指引
4. 调整延迟时间
5. 测试渠道连通性

已有配置的渠道会标注当前状态，支持随时修改。

方式二：手动编辑配置文件

创建配置文件 ~/.claude/hooks/notify.json，可从模板复制后编辑：

# marketplace 安装：从项目仓库获取模板
curl -sL https://raw.githubusercontent.com/MarioZZJ/cc-notify-hooks/main/config/notify.example.json \
  -o ~/.claude/hooks/notify.json

# 本地 clone：直接复制
cp config/notify.example.json ~/.claude/hooks/notify.json

然后编辑配置文件，将你需要的渠道设为 "enabled": true 并填入凭证：

{
  "channels": {
    "macos": { "enabled": true, "delay": 3, "events": ["notification"] },
    "bark":  { "enabled": true, "delay": 15, "key": "your-key", "server": "https://api.day.app" },
    "telegram": { "enabled": true, "delay": 5, "bot_token": "123:ABC", "chat_id": "123456" }
  },
  "rate_limit": 10
}