内容来源：alexop.dev。https://alexop.dev/posts/claude-code-notification-hooks/
原题：Claude Code Notifications: Get Alerts When Tasks Finish (Hooks Setup)
原发布时间：2025-11-23

使用 Hooks 配置 Claude Code 桌面通知，在任务结束、需要输入或请求权限时收到提醒，不必一直盯着终端。

环境说明（核对于 2026-07-20）：当前 Hooks 参考文档仍然包含 Hook 事件、permission_prompt、idle_prompt 和 $CLAUDE_PROJECT_DIR；当前文档还列出了 auth_success 与 elicitation_dialog，本文这套专用教程没有处理。示例实现仅适用于 macOS，因为使用了 osascript，而且需要 npx、tsx 和 @anthropic-ai/claude-agent-sdk。Windows 或 Linux 用户需要替换通知命令。

文章社交分享图

你正在专心工作，Claude Code 也在运行自己的任务。五分钟后回来看一眼，它还在等待；十分钟后再看，仍然在等待。

如果能准确知道 Claude 什么时候真正需要你，不是很好吗？

这就是 Hooks 的用途。Claude Code 会在工作流的特定节点运行 Hooks。你可以利用这些 Hooks 发送桌面通知，从而不会错过重要时刻。

但如果以前从未使用 Hooks，这个概念可能有些抽象。下面逐步解释。

什么是 Hooks？

Hooks 是在 Claude Code 生命周期特定节点运行的命令，让你无须一直盯着 CLI，也能响应事件。不必反复检查，而是让系统主动通知。

Claude Code 提供两种通知类型：

• permission_prompt——Claude 需要获得操作权限
• idle_prompt——Claude 正在等待用户输入

可以把它们理解为本机版 Webhook。Claude Code 触发事件，用户的代码负责响应。

配置桌面通知

下面让它真正运行起来。只需要两部分：配置文件和通知脚本。

首先在项目中创建 .claude/hooks 目录，然后把 Hook 配置加入 .claude/settings.json：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/notification-desktop.ts\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

这段配置告诉 Claude Code：“遇到 permission_prompt 或 idle_prompt 时运行这条命令。”timeout: 5 表示 Hook 最多可以运行五秒，然后 Claude 会继续。

配置可以放在两个位置：

• .claude/settings.json——项目专用，可以提交到 Git 并与团队共享
• ~/.claude/settings.json——全局用户设置，只在个人电脑上使用

团队 Hooks 使用项目设置，个人通知使用全局设置。$CLAUDE_PROJECT_DIR 是 Claude Code 提供的环境变量，会自动展开为项目根目录。

项目结构应该如下：

└── your-project/
    ├── .claude/
    │   ├── settings.json  Hook 配置
    │   └── hooks/
    │       └── notification-desktop.ts  通知脚本
    ├── src  ...
    └── package.json  ...

通知脚本

创建 .claude/hooks/notification-desktop.ts。这份脚本负责真正发送通知：

#!/usr/bin/env npx tsx
/* eslint-disable node/prefer-global/process */
/**
 * Claude Code Notification Hook - 桌面提醒
 *
 * Claude 需要用户注意时发送系统通知：
 * - 权限提示
 * - 空闲提示，等待输入
 */

import type { NotificationHookInput } from '@anthropic-ai/claude-agent-sdk'

import { execSync } from 'node:child_process'
import { readFileSync } from 'node:fs'

function readStdin(): string {
  return readFileSync(0, 'utf-8')
}

function sendMacNotification(title: string, message: string): void {
  // 转义 AppleScript 特殊字符
  const escapedTitle = title.replace(/"/g, '\\"')
  const escapedMessage = message.replace(/"/g, '\\"')

  const script = `display notification "${escapedMessage}" with title "${escapedTitle}" sound name "Ping"`

  try {
    execSync(`osascript -e '${script}'`, { stdio: 'ignore' })
  }
  catch {
    // 通知失败时静默忽略
  }
}

function main(): void {
  const rawInput = readStdin()

  let parsedInput: unknown
  try {
    parsedInput = JSON.parse(rawInput)
  }
  catch {
    process.exit(0)
  }

  const input = parsedInput as NotificationHookInput

  const notificationType = (input as { notification_type?: string }).notification_type
  const message = input.message

  switch (notificationType) {
    case 'permission_prompt':
      sendMacNotification('Claude Code - 需要权限', message || 'Claude 需要你的授权才能继续')
      break
    case 'idle_prompt':
      sendMacNotification('Claude Code - 正在等待', message || 'Claude 正在等待你的输入')
      break
    default:
      // 其他类型不发送通知
      break
  }

  process.exit(0)
}

main()

它真正发挥价值的时刻

基础配置已经完成，下面说说它什么时候最有用。

当你正在深度专注，而 Claude Code 运行长时间操作时，这套通知系统尤其有价值。不必每隔几秒检查终端。需要立即处理的权限请求会使用一种声音提醒；用户离开后出现的空闲等待，则可以用较柔和的提示把注意力拉回来。

关键在于，通知会在真正需要用户参与的时刻准确到达，不早也不晚。

想继续深入？还可以构建使用 Hooks 的自定义插件，在不同项目之间实现更强大的自动化。

结论

Hooks 会把 Claude Code 从一款需要用户盯着看的工具，变成替用户主动观察的工具。

整个配置大约只需要五分钟：复制配置、创建脚本，再根据喜好调整提示音。之后就完成了。不必再反复切换上下文，也不用每隔几秒瞥一眼终端，猜测 Claude 是否需要自己。通知会在真正重要时准确到达。

真正的价值不在于自动发送通知，而在于重新拿回专注力。Claude Code 工作时，你也可以继续自己的工作，只有真正需要时才重新投入注意力。只配置一次，就能开启一种更好的 AI 协作方式。