Claude Code Notify

当 Claude Code 需要你的确认、或完成回复时，弹出 Windows 系统 Toast 通知。点击通知自动切换回终端窗口。终端在前台时静默不打扰。

Windows 10/11 · Claude Code v2.1+ · 无需管理员权限

为什么需要这个？

Claude Code 在处理长时间任务时，你会切到其他窗口。当它需要权限确认或任务完成时，你无法感知——除非一直盯着终端。

这个项目给 Claude Code 接入了 Windows 原生通知系统：权限弹窗、任务完成，都会像微信消息一样在通知中心弹出。不在终端前时提醒你，在终端前时自动静默。

安装

powershell -ExecutionPolicy Bypass -File install.ps1

一行完成。重启 Claude Code 生效。

卸载

powershell -ExecutionPolicy Bypass -File uninstall.ps1

工作流程

你在浏览器里看文档
      ↓
Claude 完成任务 / 需要权限确认
      ↓
 ┌─────────────────────────────┐
 │  🔔 Claude Code             │
 │  Claude 需要你的确认        │
 │              [ 切换至终端 ] │
 └─────────────────────────────┘
      ↓  点击 Toast
终端自动切到前台，Claude Code 选项卡已就绪

架构

settings.json                Hook 层 (何时触发)
    │                         Notification hook
    │                         ├─ permission_prompt (权限弹窗)
    │                         └─ Stop             (回复完成)
    ↓
notify-*.ps1                过滤层 (是否需要弹?)
    │                         GetForegroundWindow()
    │                         ├─ 终端在前台 → exit 0
    │                         └─ 不在      → 发 Toast
    ↓
Windows Toast API            通知层 (弹什么?)
    │                         activationType="protocol"
    │                         launch="claude-focus://"
    ↓  用户点击
claude-focus:// 协议         响应层 (点击后干嘛?)
    │                         注册表 HKCU\Software\Classes
    │                         → wscript.exe //B focus-terminal.vbs
    ↓
focus-terminal.vbs           切换层 (怎么切?)
                              WMI 枚举终端进程
                              AppActivate(PID) → 终端到前台

关键设计决策

为什么用 VBScript 而不是 PowerShell 处理点击？

powershell.exe 是控制台子系统程序，启动时 Windows 会短暂闪现一个黑窗口。wscript.exe 是 GUI 子系统，天生无窗口。从 Toast 点击到终端切换全程无闪现。

为什么用 PID 而不是窗口标题来定位终端？

窗口标题含中文/Emoji 时，写文件→读文件过程中编码不一致会导致匹配失败。进程 PID 是纯数字，零编码损耗。

为什么要检测前台窗口？

如果不检测，你在终端前打字时也会弹通知——纯骚扰。GetForegroundWindow() 是 Win32 API，零开销判断当前前台是否已是终端。

常见问题

通知没声音？

检查 Windows 音量合成器中「系统声音」的滑块是否被拉低。Toast 声音走的是系统通知通道，不是扬声器主通道。

VS Code 扩展里不弹通知？

这是 Claude Code 的已知限制（#28774），Notification hook 在 VS Code 扩展中不触发。终端中使用正常。

点击通知后跳转到错误的选项卡？

Windows Terminal 所有选项卡共享一个窗口句柄，无法在外部区分。如果通知发出后你在 WT 中切换了选项卡，点击会回到窗口但选项卡保持当前选中状态。

能否自定义提示音？

修改 notify-permission.ps1 / notify-stop.ps1 中 Toast XML 的 <audio> 标签，例如：

<audio src="ms-winsoundevent:Notification.Looping.Alarm" loop="false" />

可选值：Notification.Default、Notification.IM、Notification.Mail、Notification.Reminder、Notification.Looping.Alarm、Notification.Looping.Call。

文件结构

├── install.ps1                # 一键安装
├── uninstall.ps1              # 一键卸载
├── README.md
└── src/
    ├── notify-permission.ps1  # 权限通知 + 前台检测
    ├── notify-stop.ps1        # 完成通知 + 前台检测
    ├── focus-terminal.vbs     # 点击 Toast → 切换终端
    ├── register-protocol.ps1  # 注册 claude-focus:// URL 协议
    └── hooks.json             # settings.json hook 配置模板

AI 生成声明

本项目代码由 Claude Code（Anthropic）与用户协作生成。

许可证

MIT