Claude Code Hooks 学习

Claude Code Hooks

——官方 8 大事件、全部字段、10+ 脚本，一步到位

一、一分钟总览

1. Hooks = 在 Claude Code 生命周期 8 个固定节点插入「用户脚本」。
2. 用 JSON 声明，分「全局」(~/.claude/settings.json) 与「项目」(.claude/settings.local.json)。
3. 每个 Hook 由「事件 + 匹配器 + 命令」三元组组成。
4. 官方事件 8 个，变量 10+ 个，全部列在后面。

二、官方 8 大事件全表

三、配置文件结构（全局 vs 项目）
路径规则
• 全局：~/.claude/settings.json
• 项目：.claude/settings.local.json（优先级高）

最小合法骨架

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo PreToolUse" }
        ]
      }
    ]
  }
}

字段说明

四、匹配器（Matcher）语法精讲

1. 单工具：Bash
2. 多工具：Edit|Write|MultiEdit
3. 正则：Bash(rm -rf .*) 仅匹配含 rm -rf 的 Bash 命令
4. 通配：* 匹配所有

五、官方环境变量全集

六、可视化配置 vs 手写 JSON
• 运行 /hooks 进入 TUI，可增删改查。
• 改动后需 ccr restart 或重启 Claude Code 才生效。
• 最终仍落盘到 settings.json，可直接编辑。

七、10 个示例

1. 全局 Bash 命令审计（PreToolUse）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "command",
        "command": "jq -r '"[$(date -Iseconds)] $tool_name: $tool_input.command"' > ~/.claude/audit.log"
      }
    ]
  }
}

2. TypeScript 自动 Prettier（PostToolUse）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "type": "command",
        "command": "[[ "$CLAUDE_FILE_PATH" == *.ts ]] && npx prettier --write "$CLAUDE_FILE_PATH""
      }
    ]
  }
}

3. 阻止删除生产文件（PreToolUse）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "script",
        "script": ".claude/hooks/protect_rm.sh"
      }
    ]
  }
}

protect_rm.sh

#!/usr/bin/env bash
set -e
cmd=$(jq -r '.tool_input.command'  "$CLAUDE_TOOL_INPUT")
[[ $cmd =~ rm -rf.*(src|dist|.env) ]] && { echo "Protected!"; exit 2; }

4. Markdown 自动补语言标签（PostToolUse）
   Python 脚本：.claude/hooks/md_lang.py

#!/usr/bin/env python3
import re, json, sys, os
path = os.environ["CLAUDE_FILE_PATH"]
if not path.endswith(".md"): sys.exit(0)
with open(path) as f: txt = f.read()
new = re.sub(r"```n(.*?)n```", lambda m: f"```{guess(m.group(1))}n{m.group(1)}n```", txt, flags=re.S)
if new != txt:
    with open(path,"w") as f: f.write(new)
    os.system(f"git add {path}")
def guess(code):
    if re.search(r"^s*(import|def|class)s", code, re.M): return "python"
    if re.search(r"^s*(const|let|function|import)s", code, re.M): return "javascript"
    return ""

Hook 配置

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "type": "script",
        "script": ".claude/hooks/md_lang.py"
      }
    ]
  }
}

5. 桌面通知“等你输入”（Notification）

{
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "type": "command",
        "command": "notify-send Claude "$CLAUDE_NOTIFICATION_TEXT""
      }
    ]
  }
}

6. 会话启动打印欢迎横幅（SessionStart）

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "type": "command",
        "command": "echo 'Welcome to Claude Code 🧑‍💻' | lolcat"
      }
    ]
  }
}

7. 子代理结束统计（SubagentStop）

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "*",
        "type": "command",
        "command": "jq -c '{agent: env.CLAUDE_SUBAGENT_NAME, status: env.CLAUDE_SUBAGENT_RESULT}' >> ~/.claude/subagent-report.jsonl"
      }
    ]
  }
}

8. 压缩前备份对话（PreCompact）

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "*",
        "type": "command",
        "command": "cp ~/.claude/session.json ~/.claude/session-backup-$(date +%s).json"
      }
    ]
  }
}

9. 用户提示强制加前缀（UserPromptSubmit）

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "type": "script",
        "script": ".claude/hooks/prefix.sh"
      }
    ]
  }
}

prefix.sh

#!/usr/bin/env bash
prompt=$(jq -r '.'  "$CLAUDE_PROMPT")
new="[SAFE MODE] $prompt"
jq -n --arg p "$new" '$p'

10. Stop 事件自动提交 Git（Stop）

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "type": "command",
        "command": "git add -A && git commit -m 'claude auto save'"
      }
    ]
  }
}

八、调试与故障排查官方清单

1. /hooks → TUI 查看配置。
2. ccr restart 让修改生效。
3. /debug 打开详细日志。
4. 本地单测：

   CLAUDE_EVENT=PreToolUse 
   CLAUDE_TOOL_INPUT='{"tool_input":{"command":"ls"}}' 
   ./your-hook.sh
   

5. 日志追加：脚本首行 exec >> ~/.claude/hooks.log 2>&1 && set -x

九、安全红线（官方原文提炼）

• Hook 以当前用户身份执行，勿用 root 跑 Claude Code。
• 避免 eval、bash -c "$untrusted"。
• 项目级钩子优先，全局钩子仅放审计类脚本。
• 审查第三方脚本后再启用。

十、一键速查表（打印贴墙）

结语
掌握「8 大事件 + 2 个配置文件 + 10+ 环境变量」，你就能把 Claude Code 变成：

• 自动格式化器
• 文件守护者
• 审计机器人
• 通知中心

文章来源于互联网:Claude Code Hooks 学习

相关推荐: AI人工智能领域，文心一言的技术架构

文心一言的技术架构解析 关键词：文心一言、大语言模型、Transformer架构、知识增强、ERNIE、深度学习、自然语言处理 摘要：本文深入解析百度文心一言的技术架构，从其底层的大语言模型基础到顶层的应用实现。我们将详细探讨文心一言的核心技术原理，包括其基于…