Hooks 钩子系统

在理解 hooks 之前，让我们先回顾一下正常流程。当你向 Claude Code 提出问题时， 你的查询会被发送到 Claude 模型以及工具定义。Claude 模型可能会决定运行一个工具， 然后由 Claude Code 执行该工具并返回结果。

Hooks 在这个过程中插入自身， 允许你在工具执行之前或之后执行代码。

Hooks 在 Claude 设置文件中定义。你可以将它们添加到：

配置文件包含两个主要部分：

{
  "PreToolUse": [
    {
      "matcher": "Read",
      "hooks": [
        {
          "type": "command",
          "command": "node /home/hooks/read_hook.ts"
        }
      ]
    }
  ]
}

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [
        {
          "type": "command",
          "command": "node /home/hooks/edit_hook.ts"
        }
      ]
    }
  ]
}

PreToolUse hooks 会接收 Claude 想要执行的工具调用的详细信息。你可以：

由于工具调用已经发生，PostToolUse hooks 无法阻止操作。 但它们可以：

// 运行代码质量检查
// 运行类型检查
// 将结果反馈给 Claude
// Claude 可能根据反馈更新刚写入的文件

创建 hook 需要四个主要步骤：

Claude Code 提供多个内置工具，你可以用 hooks 监控它们：

当 hook 命令执行时，Claude 通过标准输入发送 JSON 数据，包含关于建议工具调用的详细信息：

{
  "session_id": "2d6a1e4d-6...",
  "transcript_path": "/Users/sg/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/code/queries/.env"
  }
}

你的命令从标准输入读取此 JSON，解析它，然后根据工具名称和输入参数决定允许或阻止该操作。

Hook 命令通过退出码向 Claude 传递信息：

首先，我们需要在设置文件中配置 hook。打开 .claude/settings.local.json 文件， 创建一个 PreToolUse hook，因为我们想在工具执行前拦截调用。

"matcher": "Read|Grep"

"command": "node ./hooks/read_hook.js"

{
  "PreToolUse": [
    {
      "matcher": "Read|Grep",
      "hooks": [
        {
          "type": "command",
          "command": "node ./hooks/read_hook.js"
        }
      ]
    }
  ]
}

当 Claude 尝试使用工具时，你的 hook 会通过标准输入作为 JSON 接收关于该调用的详细信息。此数据包括：

Hook 脚本处理此数据，可以通过退出特定代码来允许操作继续或阻止它。

Hook 脚本需要从标准输入读取工具调用数据，并检查 Claude 是否试图访问 .env 文件。以下是核心逻辑：

async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());

  // 提取 Claude 试图读取的文件路径
  const readPath =
    toolArgs.tool_input?.file_path ||
    toolArgs.tool_input?.path ||
    "";

  // 检查 Claude 是否试图读取 .env 文件
  if (readPath.includes('.env')) {
    console.error("You cannot read the .env file");
    process.exit(2);
  }

  // 允许其他操作
  process.exit(0);
}

main();

保存配置和 hook 脚本后，重启 Claude Code 使更改生效。然后通过要求 Claude 读取 .env 文件来测试它。

这种方法提供了几个优势：

以下是保护 .env 文件的完整示例总结：

{
  "PreToolUse": [{
    "matcher": "Read|Grep",
    "hooks": [{
      "type": "command",
      "command": "node ./hooks/read_hook.js"
    }]
  }]
}

async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());
  const readPath = toolArgs.tool_input?.file_path ||
                  toolArgs.tool_input?.path || "";

  if (readPath.includes('.env')) {
    console.error("不能读取 .env 文件");
    process.exit(2);
  }

  process.exit(0);
}

main();

以下是使用 hooks 的更多方式：

在使用 hooks 时，你可能会遇到一些需要注意的情况：

.claude/
├── settings.json        # 项目共享配置
└── settings.local.json  # 个人本地配置

"command": "/absolute/path/to/hooks/read_hook.js"  // ✅ 安全
"command": "./hooks/read_hook.js"                   // ❌ 不安全

// settings.example.json
{
  "PreToolUse": [{
    "matcher": "Read|Grep",
    "hooks": [{
      "type": "command",
      "command": "node $PWD/hooks/read_hook.js"
    }]
  }]
}

Claude Code hooks 可以帮助解决 AI 辅助开发中的常见弱点，特别是在大型项目中。 这些 hooks 在 Claude 修改代码时自动运行，提供即时反馈并防止常见问题。

{
  "PostToolUse": [{
    "matcher": "Write|Edit|MultiEdit",
    "hooks": [{
      "type": "command",
      "command": "npm run type-check"
    }]
  }]
}

{
  "PostToolUse": [{
    "matcher": "Write|Edit|MultiEdit",
    "hooks": [{
      "type": "command",
      "command": "node ./hooks/check-duplicates.js"
    }]
  }]
}