Claude Code 提供了强大的 Hooks 机制，允许你在特定事件发生时执行自定义脚本。本文通过一个实际案例——为权限请求添加桌面通知——来介绍 Hooks 的配置和使用。

为什么需要 Hooks？

使用 Claude Code 时，你可能需要频繁确认权限请求（执行命令、写文件等）。如果不想一直盯着终端，可以通过 Hooks 在需要确认时发送桌面通知。

Hooks 事件类型

事件	触发时机
PreToolUse	工具执行前
PostToolUse	工具执行后
PermissionRequest	需要用户确认权限时
Notification	Claude 发送通知时
Stop	响应完成时
SessionStart	会话启动时
SessionEnd	会话结束时

配置文件位置

按优先级从高到低：

1. ~/.claude/settings.local.json — 本地设置（不提交版本控制）
2. .claude/settings.json — 项目级设置
3. ~/.claude/settings.json — 用户全局设置

实战：权限请求桌面通知

1. 创建通知脚本

mkdir -p ~/.claude/hooks

创建 ~/.claude/hooks/permission-notify.sh：

#!/bin/bash
1. 开发者工具风格通知

notify-send -u critical \
    -i dialog-question \
    "Dev" \
    "Input required" \
    -t 0

1. 播放提示音
if command -v paplay &> /dev/null; then
    paplay /usr/share/sounds/freedesktop/stereo/message-new-instant.oga 2>/dev/null &
elif command -v canberra-gtk-play &> /dev/null; then
    canberra-gtk-play -i message-new-instant 2>/dev/null &
fi

exit 0

设置执行权限：

chmod +x ~/.claude/hooks/permission-notify.sh

2. 配置 Hooks

编辑 ~/.claude/settings.json：

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/你的用户名/.claude/hooks/permission-notify.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. 配置结构说明

hooks
└── PermissionRequest          # 事件类型
    └── [matcher 配置]
        ├── matcher: "*"       # 匹配规则（* 表示匹配所有）
        └── hooks              # 要执行的 hook 列表
            ├── type           # hook 类型：command / prompt / agent
            ├── command        # 要执行的命令（绝对路径）
            └── timeout        # 超时时间（秒）

Hook 类型

类型	说明
command	执行 shell 命令
prompt	使用 LLM 评估提示词
agent	启动 agent 进行验证

其他实用场景

文件保护（PreToolUse）

防止修改特定文件：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/file-protection.sh"
          }
        ]
      }
    ]
  }
}

自动格式化（PostToolUse）

文件写入后自动格式化：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

任务完成通知（Stop）

Claude 完成响应时通知：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/task-complete-notify.sh"
          }
        ]
      }
    ]
  }
}

环境变量

Hook 脚本中可用的环境变量：

变量	说明
CLAUDE_TOOL_NAME	当前工具名称
CLAUDE_FILE_PATH	操作的文件路径

注意事项

1. 安全性：只使用你信任的脚本，定期审查 hook 配置
2. 性能：设置合理的 timeout，避免阻塞操作
3. 调试：使用 /hooks 命令查看和管理已配置的 hooks
4. 路径：command 建议使用绝对路径

总结

Hooks 让 Claude Code 具备了高度可定制性。通过监听不同事件，你可以：

• 添加桌面通知，解放注意力
• 保护关键文件不被意外修改
• 自动化代码格式化、lint 检查
• 记录操作日志
• 集成其他开发工具

掌握 Hooks，让 Claude Code 更好地融入你的工作流。