【Claude Code系列教程】 hooks

了解如何通过注册 shell 命令来自定义和扩展 Claude Code 的行为。

其实claude code的调度思路，和微软的multiagents框架autogen的思路，挺像的。虽然没有复用代码。

Claude Code hooks 是用户自定义的 shell 命令，会在 Claude Code 生命周期的不同阶段执行。Hooks 提供了对 Claude Code 行为的确定性控制，确保某些操作总是执行，而不是依赖 LLM 自行决定是否执行。

要查看 hooks 的参考文档，请参阅 [Hooks reference]。

一些 hooks 的典型用例包括：

Notifications：自定义当 Claude Code 等待你输入或授权时的通知方式。
Automatic formatting：每次文件编辑后自动执行 prettier（用于 .ts 文件）、gofmt（用于 .go 文件）等。
Logging：记录和统计所有执行的命令，以满足合规性或调试需要。
Feedback：当 Claude Code 生成不符合你代码规范的代码时，提供自动反馈。
Custom permissions：阻止对生产文件或敏感目录的修改。

将这些规则编码为 hooks，而不是提示语（prompt）指令，你就把建议变成了每次都自动执行的应用级代码。

⚠️ 添加 hooks 时必须考虑安全影响，因为 hooks 会在 agent 循环中自动执行，并拥有你当前环境的权限。例如，恶意的 hooks 代码可能会窃取你的数据。在注册 hooks 之前，请务必审查其实现。

关于完整的安全最佳实践，请参见 hooks 参考文档中的 [Security Considerations]。

Hook Events Overview

Claude Code 提供多个 hook 事件，它们在工作流的不同阶段触发：

PreToolUse：在工具调用之前运行（可以阻止调用）
PostToolUse：在工具调用完成后运行
Notification：当 Claude Code 发出通知时运行
Stop：Claude Code 响应结束时运行
Subagent Stop：subagent 任务完成时运行

每个事件会接收不同的数据，并可在不同层面控制 Claude 的行为。

Quickstart

本快速开始示例将添加一个 hook，用于记录 Claude Code 执行的 shell 命令。

Prerequisites

安装 jq，用于命令行中处理 JSON。

Step 1: 打开 hooks 配置

运行 /hooks slash 命令，选择 PreToolUse hook 事件。

PreToolUse hooks 会在工具调用之前运行，并可阻止这些调用，同时给 Claude 提供修改建议。

Step 2: 添加 matcher

选择 + Add new matcher...，仅在 Bash 工具调用时运行你的 hook。

输入 Bash 作为 matcher。

你也可以使用 * 来匹配所有工具。

Step 3: 添加 hook

选择 + Add new hook... 并输入以下命令：

javascript 复制代码

jq -r '"(.tool_input.command) - (.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

Step 4: 保存你的配置

在 storage location 处选择 User settings，因为你是将日志写入主目录。此 hook 将适用于所有项目，而不仅仅是当前项目。

然后按下 Esc，返回到 REPL。你的 hook 已经注册成功！

Step 5: 验证你的 hook

再次运行 /hooks，或查看 ~/.claude/settings.json，你会看到如下配置：

bash 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

Step 6: 测试你的 hook

请求 Claude 执行一个简单命令，如 ls，然后查看日志文件：

bash 复制代码

cat ~/.claude/bash-command-log.txt

你应该能看到如下条目：

bash 复制代码

ls - Lists files and directories

更多示例

Code Formatting Hook

在编辑后自动格式化 TypeScript 文件：

bash 复制代码

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo "$file_path" | grep -q '\.ts$'; then npx prettier --write "$file_path"; fi; }"
          }
        ]
      }
    ]
  }
}

Custom Notification Hook

当 Claude 需要输入时，触发桌面通知：

json 复制代码

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

File Protection Hook

阻止对敏感文件的修改：

kotlin 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c "import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)""
          }
        ]
      }
    ]
  }
}

Learn more

查看 hooks 的参考文档，请访问 Hooks reference。
阅读完整的安全最佳实践与安全指导，请参阅 Security Considerations in the hooks reference documentation。
查找故障排查步骤与调试技术，请访问 Debugging in the hooks reference documentation。