Claude Code Task Notify

Claude Code 任务完成弹窗通知:每轮任务结束自动弹出系统通知,内容显示本轮工作成果摘要(交付报告),而非「好的」「完成」这类过程短句。

支持两种运行环境,自动选择:

环境	机制	文件
Windows 宿主机直接运行	BurntToast 系统通知(Windows 通知中心)	hooks/toast-popup.ps1
Docker 容器(Linux)运行	容器 hook → 宿主网关 /api/notify → 宿主系统 toast	hooks/notify-done.sh + hooks/notify-send.js

功能特性

• ✅ 每轮任务结束自动通知(Stop hook,Claude 完成响应时触发)
• ✅ 摘要提取:从后往前找第一条长度 ≥40 字符的 assistant 文本(成果摘要/交付报告通常较长,自动跳过「好的」「9 秒内退出」等过程短句),找不到时回退最后一条非空文本
• ✅ 通知中心留存:错过弹窗仍可在 Windows 通知中心找到
• ✅ 限流:宿主 60s / 容器 300s 内不重复通知,避免短会话轰炸
• ✅ 零外部依赖(Windows 侧需 BurntToast PowerShell 模块,一条命令安装)

架构

┌─ 宿主(Windows)直接运行 ─────────────────────────────┐
│  Claude Code 完成响应 → Stop hook                     │
│    → hooks/toast-popup.ps1                            │
│    → 读 transcript → 提取成果摘要 → BurntToast 弹窗    │
└──────────────────────────────────────────────────────┘

┌─ Docker 容器(Linux)运行 ─────────────────────────────┐
│  Claude Code(容器内)完成响应 → Stop hook              │
│    → notify-done.sh(限流 300s)                        │
│    → notify-send.js 读取 transcript 提取摘要          │
│    → POST 宿主网关 /api/notify {text}                 │
│    → 宿主 PowerShell 弹系统 toast                     │
└──────────────────────────────────────────────────────┘

安装

1. 放置 hook 文件

# Windows 宿主机
mkdir ~\.claude\hooks
copy hooks\toast-popup.ps1 ~\.claude\hooks\

# Docker 容器(假设容器内 Claude 配置目录挂载为 /home/node/.claude)
copy hooks\notify-done.sh hooks\notify-send.js <容器挂载目录>\hooks\

2. 安装 BurntToast(Windows 宿主机)

Install-Module BurntToast -Scope CurrentUser -Force

3. 配置 Claude Code hooks

在 ~/.claude/settings.json 添加(宿主机方案):

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File C:/Users/<USER>/.claude/hooks/toast-popup.ps1"
          }
        ]
      }
    ]
  }
}

容器方案在容器内 ~/.claude/settings.json 添加:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /home/node/.claude/hooks/notify-done.sh"
          }
        ]
      }
    ]
  }
}

注:Stop hook 在 Claude 主 agent 完成响应时触发;用户中断(ESC)或 API 错误时不触发(触发的是 StopFailure,可按需另行配置)。

4. 网关 /api/notify 端点(仅容器方案需要)

容器方案需要宿主网关暴露 POST /api/notify,接收 {"text": "摘要"},随后在宿主执行 PowerShell 弹 toast。参考实现见 docs/gateway-notify-example.js(可按你的网关/代理框架改造)。

配置项(容器方案)

环境变量	默认值	说明
NOTIFY_HOST	host.docker.internal	宿主网关地址
NOTIFY_PORT	7860	宿主网关端口
HOOK_DEBUG_LOG	(空,关闭)	调试日志路径,如 /home/node/.claude/hooks/hook-debug.log

已知坑(踩坑记录)

1. PowerShell 5.1 GBK 编码:transcript 是 UTF-8,Get-Content 必须显式 -Encoding UTF8,否则长中文行 JSON 结构被破坏,ConvertFrom-Json 静默失败 → 摘要退化为短句
2. WPF 自绘弹窗在 hook 子进程不可见:脚本执行成功、无报错,但窗口不渲染。故改用 BurntToast 系统通知(通知中心可见、有留存)
3. 容器内管道 stdin:直接管道喂 node 时 end 事件可能不触发导致挂起,需先落盘临时文件再重定向
4. 脚本行尾:.sh 必须 LF,CRLF 会导致 then/fi 语法错误

隐私声明

本仓库不包含任何敏感信息:

• ❌ 无 API Key / Token / 认证凭据
• ❌ 无本地绝对路径(脚本全部使用 $PSScriptRoot 相对路径,网关地址/端口走环境变量)
• ❌ 无任何模型供应商配置、代理配置

部署时请自行替换 settings.json 示例中的 <USER> 占位符。

License

MIT