Hooks 系统

通过 Hooks 自定义 Claude Code 的行为 — 自动格式化、安全拦截、通知推送等

Hooks 系统 ¶

Hooks 允许你在 Claude Code 的关键生命周期节点插入自定义逻辑，例如自动格式化代码、拦截危险命令、发送通知等。

核心概念 ¶

每个 Hook 由三部分组成：

事件：触发时机（如 PreToolUse — 工具执行前）
匹配器：可选的工具名过滤（如只匹配 Bash 或 Write）
处理器：Shell 命令、提示词或子代理

常用事件 ¶

事件	触发时机	可否阻断	典型用例
`PreToolUse`	工具执行前	是（exit code 2）	安全拦截、文件保护
`PostToolUse`	工具执行后	否	自动 lint/格式化
`Notification`	Claude 发送通知时	否	Slack/飞书告警
`UserPromptSubmit`	用户提交提示时	是	上下文增强
`Stop`	Claude 完成响应时	否	质检、摘要
`SessionStart`	会话启动时	否	环境初始化

配置方式 ¶

在 .claude/settings.json（项目级）或 ~/.claude/settings.json（用户级）中添加：

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

实用示例 ¶

1. 文件保存后自动格式化 ¶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}

2. 拦截危险的 Shell 命令 ¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE 'rm -rf|sudo|git push --force' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

exit 2 会阻断工具执行，exit 0 允许继续。

3. 保护敏感文件不被读取 ¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE '\\.env|credentials|secret' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

4. 任务完成后发送通知 ¶

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"$NOTIFICATION_MESSAGE\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}