Claude Code hooks 是用户定义的 shell 命令，在 Claude Code 生命周期的各个点执行。Hooks 提供对 Claude Code 行为的确定性控制，确保某些操作始终发生，而不是依赖 LLM 选择运行它们。

有关 hooks 的参考文档，请参阅 Hooks 参考。

hooks 的示例用例包括：

  • 通知：自定义当 Claude Code 等待您的输入或运行权限时如何获得通知。
  • 自动格式化：在每次文件编辑后对 .ts 文件运行 prettier，对 .go 文件运行 gofmt 等。
  • 日志记录：跟踪和计算所有执行的命令，用于合规性或调试。
  • 反馈：当 Claude Code 生成不符合您代码库约定的代码时提供自动反馈。
  • 自定义权限：阻止对生产文件或敏感目录的修改。

通过将这些规则编码为 hooks 而不是提示指令，您将建议转换为应用程序级代码，每次预期运行时都会执行。

在添加 hooks 时，您必须考虑 hooks 的安全影响，因为 hooks 在代理循环期间使用您当前环境的凭据自动运行。 例如，恶意 hooks 代码可能会泄露您的数据。在注册 hooks 之前，请始终检查您的 hooks 实现。

有关完整的安全最佳实践，请参阅 hooks 参考文档中的安全注意事项。

​
Hook 事件概述

Claude Code 提供了几个在工作流程不同点运行的 hook 事件：

  • PreToolUse：在工具调用之前运行（可以阻止它们）
  • PostToolUse：在工具调用完成后运行
  • Notification：当 Claude Code 发送通知时运行
  • Stop：当 Claude Code 完成响应时运行
  • SubagentStop：当子代理任务完成时运行

每个事件接收不同的数据，并可以以不同的方式控制 Claude 的行为。

​
快速入门

在这个快速入门中，您将添加一个记录 Claude Code 运行的 shell 命令的 hook。

​
先决条件

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

​
步骤 1：打开 hooks 配置

运行 /hooks 斜杠命令并选择 PreToolUse hook 事件。

PreToolUse hooks 在工具调用之前运行，可以阻止它们，同时为 Claude 提供关于如何做不同事情的反馈。

​
步骤 2：添加匹配器

选择 + Add new matcher… 仅在 Bash 工具调用上运行您的 hook。

为匹配器输入 Bash。

使用空字符串 "" 来匹配所有工具。* 字符本身不是有效的匹配器。

​
步骤 3：添加 hook

选择 + Add new hook… 并输入此命令：

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

​
步骤 4：保存您的配置

对于存储位置，选择 User settings，因为您正在记录到您的主目录。然后此 hook 将应用于所有项目，而不仅仅是您当前的项目。

然后按 Esc 直到返回到 REPL。您的 hook 现在已注册！

​
步骤 5：验证您的 hook

再次运行 /hooks 或检查 ~/.claude/settings.json 以查看您的配置：

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

​
步骤 6：测试您的 hook

要求 Claude 运行一个简单的命令，如 ls，并检查您的日志文件：

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

您应该看到类似以下的条目：

ls - Lists files and directories

​
更多示例

有关完整的示例实现，请参阅我们公共代码库中的 bash 命令验证器示例。

​
代码格式化 Hook

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

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

​
自定义通知 Hook

当 Claude 需要输入时获取桌面通知：

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

​
文件保护 Hook

阻止对敏感文件的编辑：

{
  "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)\""
          }
        ]
      }
    ]
  }
}

​
了解更多

  • 有关 hooks 的参考文档，请参阅 Hooks 参考。
  • 有关全面的安全最佳实践和安全指南，请参阅 hooks 参考文档中的安全注意事项。
  • 有关故障排除步骤和调试技术，请参阅 hooks 参考文档中的调试。