cc-notify-hooks

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

为什么需要分级通知？

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

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

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

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

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

支持的渠道

短通知渠道（即时触达）

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

渠道	默认延迟	说明
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 事件
    │
    ├─ Codex request_user_input → PreToolUse dispatcher → 等待输入通知
    │                                      └─ PostToolUse → 定向取消
    ▼
notify.sh ── 清除当前 Session 的旧 pending → 创建新 pending
    │
    │  ┌── 短通知 ──────────────────────────────────┐
    ├─ │ 3s  → pending 还在？ → macOS 系统通知      │
    ├─ │ 5s  → pending 还在？ → Telegram             │
    ├─ │ 15s → pending 还在？ → Bark / ntfy / ...    │
    │  └────────────────────────────────────────────┘
    │  ┌── 长通知 ──────────────────────────────────┐
    └─ │ 5m  → pending 还在？ → 企微 / 飞书 / Slack │
       └────────────────────────────────────────────┘

用户回来操作（发消息 / 回答问题 / 点权限按钮）
    └─→ clear_pending.sh → 清除当前 Session 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 用户）

仓库根目录的 .agents/plugins/marketplace.json 是 Codex marketplace，实际插件目录是 plugins/cc-notify-hooks/。在终端执行：

codex plugin marketplace add MarioZZJ/cc-notify-hooks --ref v2.3.1
codex plugin add cc-notify-hooks@cc-notify-hooks

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

[features]
codex_hooks = true

之后重启 Codex，或在新会话中使用插件。安装或升级后，打开 /hooks 审阅并信任新增或变更的 hook 定义，否则 Codex 会跳过它们。

注意：Codex 的 hook 命令运行目录是当前会话 cwd，不是插件根目录。.codex-plugin/plugin.json 只负责把 hooks/codex-hooks.json 作为生命周期配置打包进去；hook 命令不能写成 ./scripts/...。本插件使用 Codex 提供的 PLUGIN_ROOT 定位脚本、使用 PLUGIN_DATA 保存插件配置和状态，因此兼容自定义 CODEX_HOME，不依赖固定的插件缓存路径。

方式三：本地插件模式

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

# Claude Code
claude --plugin-dir ./cc-notify-hooks/plugins/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 user-input   # 验证 request_user_input dispatcher 与模板
bash test_notify.sh state        # 验证多 Session 状态隔离与精确去重
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/plugins/cc-notify-hooks/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
}

完整配置模板见 config/notify.example.json。

字段说明

字段	说明
enabled	是否启用该渠道
delay	推送延迟（秒），可自由调整
events	可选，响应的事件类型，默认 ["notification", "stop"]。Codex 等待输入在内部标记为 user_input，渠道过滤仍按 notification，旧配置无需修改
format	可选，长通知渠道的展示格式。飞书默认 card，企业微信/钉钉/Slack 默认 markdown，Discord 默认 embed
其他字段	各渠道的凭证（key、webhook、token 等）

各渠道凭证

Bark

1. 安装 Bark App
2. 首页推送 URL https://api.day.app/xxxxxxxx，xxxxxxxx 即为 key
3. 自建服务器设置 server 字段

Telegram

1. 在 Telegram 中找 @BotFather，创建 Bot，获取 bot_token
2. 向你的 Bot 发一条消息
3. 访问 https://api.telegram.org/bot<TOKEN>/getUpdates 获取 chat_id

Pushover

1. 注册 pushover.net，获取 user_key
2. 创建 Application，获取 app_token

ntfy

1. 安装 ntfy App，订阅一个 topic
2. 配置 topic 字段，自建服务器设置 server

Gotify

1. 自建 Gotify 服务
2. 创建 Application，获取 app_token
3. 配置 server 和 app_token

企业微信

1. 群聊 → 右上角「⋯」→ 群机器人 → 添加 → 新创建
2. 复制 Webhook 地址到 webhook 字段

飞书

1. 群设置 → 群机器人 → 添加机器人 → 自定义机器人
2. 复制 Webhook 地址到 webhook 字段

钉钉

1. 群设置 → 智能群助手 → 添加机器人 → 自定义（关键词模式）
2. 复制 Webhook 地址到 webhook 字段
3. 关键词需包含在通知内容中（项目名通常可满足）

Slack

1. 创建 Slack App → Incoming Webhooks → 启用
2. Add New Webhook to Workspace → 选择频道
3. 复制 Webhook URL 到 webhook 字段

Discord

1. 服务器设置 → 整合 → Webhooks → 新建
2. 选择频道，复制 Webhook URL 到 webhook 字段

监听事件

Claude Code

Hook	触发时机	行为
Notification	权限确认、等待输入等	分级推送
Stop	Claude 回复结束	分级推送
UserPromptSubmit	用户发消息	清除 pending
PreToolUse	用户点权限按钮	清除 pending

Codex CLI

Hook	触发时机	行为
PermissionRequest	Codex 请求授权时	分级推送
Stop	Codex 回合结束	分级推送
UserPromptSubmit	用户发消息	清除 pending
PreToolUse	request_user_input 调用前	发送“需要回复”通知；其他工具清除当前 Session pending
PostToolUse	request_user_input 收到回答后	只取消当前 Session 尚未发送的输入通知

Codex 没有独立的等待输入事件。插件通过 PreToolUse(request_user_input) 精确识别等待状态，并复用 notification 渠道配置。

通知内容

通知先归一为统一字段，再按短通知和长通知分别渲染。标题使用实际 Agent 名，不再写死为 Claude。

场景	标题
Claude Code Notification idle_prompt	Claude Code · 等待响应 ⏳
Codex PermissionRequest	Codex · 需要确认 🔔
Codex request_user_input	Codex · 需要回复 🔔
Stop	{Agent} · 任务完成 ✅
异常 / 未知事件	{Agent} · 异常 ⚠️

短通知正文只保留打断所需信息：

[项目名] summary_short · tool_name

其中 tool_name 是条件字段，没有就不显示；permission_mode 不进入通知正文。

Codex 等待输入使用专用短正文，包含问题数和短 Session id：

[项目名] 首个问题摘要 · 2 个问题 · Session 019eabcd

长通知正文第一行显示 summary_short，随后显示定位字段：

summary_short

项目: project
事件: hook_event_name
工具: tool_name      # 有值才显示
Session: session_short

model · cwd · hostname

等待输入的长通知额外显示问题数、首题选项和完整 Session id。飞书默认发送消息卡片；企业微信、钉钉、Slack 使用近似 Markdown 模板；Discord 使用 embed。summary_short 来自 message/prompt、首个结构化问题或 last_assistant_message 的首个非空行，最长保留 120 字。

过滤规则

规则	说明
子智能体过滤	agent_id 非空时跳过
Stop 循环保护	stop_hook_active=true 时跳过
/exit 静默	只抑制当前 Session 后续的 Stop 事件
Rate Limiting	按 Session + 事件类别限流；request_user_input 使用 tool_use_id 精确去重

文件结构

cc-notify-hooks/
├── .claude-plugin/
│   ├── plugin.json -> ../plugins/cc-notify-hooks/.claude-plugin/plugin.json
│   └── marketplace.json     # Claude Code marketplace（指向 plugins/cc-notify-hooks）
├── .codex-plugin/
│   └── plugin.json -> ../plugins/cc-notify-hooks/.codex-plugin/plugin.json
├── .agents/plugins/
│   └── marketplace.json     # Codex CLI marketplace（指向 plugins/cc-notify-hooks）
├── plugins/cc-notify-hooks/ # 真实插件根目录，Claude/Codex 都从这里安装
│   ├── .claude-plugin/plugin.json
│   ├── .codex-plugin/plugin.json
│   ├── skills/config/SKILL.md
│   ├── hooks/
│   │   ├── hooks.json
│   │   └── codex-hooks.json
│   ├── scripts/
│   │   ├── notify.sh
│   │   ├── pre_tool_use.sh
│   │   ├── clear_pending.sh
│   │   └── channels/
│   ├── config/notify.example.json
│   └── test_notify.sh
├── skills -> plugins/cc-notify-hooks/skills
├── hooks -> plugins/cc-notify-hooks/hooks
├── scripts -> plugins/cc-notify-hooks/scripts
├── config -> plugins/cc-notify-hooks/config
├── install.sh               # 独立安装入口（路由）
├── install/
│   ├── claude.sh            # Claude Code 安装分支
│   └── codex.sh             # Codex CLI 安装分支
└── test_notify.sh -> plugins/cc-notify-hooks/test_notify.sh

调试日志：/tmp/claude-hooks-debug.log

卸载

Claude Code 插件：在 Claude Code 中 /plugin 管理。

Codex CLI 插件：在 Codex 中 /plugin 管理。

独立安装（Claude）：

rm -rf ~/.claude/hooks/scripts ~/.claude/hooks/notify.json ~/.claude/hooks/state
# 手动编辑 ~/.claude/settings.json 移除相关 hooks

独立安装（Codex）：

rm -rf ~/.codex/cc-notify-hooks
# 手动编辑 ~/.codex/hooks.json 移除相关事件，可选关闭 codex_hooks

License

MIT