Hooks才是Claude Code CLI 的革命性更新 --知识铺
前言
前面对Claude Code CLI有了基本了解,今天继续深度探索Claude Code CLI Hooks的使用方式。对往期内容感兴趣的小伙伴也可以看往期内容:
- Claude Code CLI平台与中转站接入汇总及避坑
- 使用Claude Code Router轻松切换各种高性价比模型
- Claude Code CLI MCP配置很难?三种方式轻松掌握
- 深入了解Claude Code CLI自定义命令
- 深入了解Claude Code CLI子代理Subagent
当前使用版本
1.0.128 (Claude Code)
配置文件
Claude Code CLI钩子配置在 settings.json文件,提供了 用户(全局)配置、项目配置、本地项目配置 3种配置方式:
- 用户(全局)配置:作用于当前用户下单所有项目,路径:~/.claude/settings.json
- 项目配置:作用于特定项目,路径:.claude/settings.json
- 本地项目配置:作用于特定本地项目(git忽略),路径:.claude/settings.local.json
钩子由匹配器组织,每个匹配器可以有多个钩子, 格式如下:
|
|
-
matcher:匹配工具名称的模式,区分大小写(仅适用于 PreToolUse 和 PostToolUse)
-
支持字符串匹配, 例如:Write匹配写入工具,Bash匹配Shell命令
-
支持正则表达式,例如:Edit|Write 或者 Notebook.*
-
使用 * 匹配所有工具,也可以不配置或者使用 ""
-
hooks:模式匹配时要执行的命令数组
-
type:目前仅支持command
-
command:要执行的Shell命令(可以使用 $CLAUDE_PROJECT_DIR 等环境变量)
-
timeout:(可选)在取消该特定命令之前,命令应运行多长时间(以秒为单位)
Hook事件及匹配器
Claude Code提供了几个在工作流程不同时间点运行的Hook事件,其中不同的Hook事件提供了不同的匹配器。
Hook事件
Claude Code Hook事件:
- PreToolUse:在工具调用之前运行(可以阻止它们)
- PostToolUse:在工具调用完成后运行
- UserPromptSubmit:在用户提交提示词时运行,在 Claude 处理之前
- Notification:在 Claude Code 发送通知时运行
- Stop:在 Claude Code 完成响应时运行
- SubagentStop:在子代理任务完成时运行
- PreCompact:在 Claude Code 即将运行压缩操作之前运行
- SessionStart:在 Claude Code 开始新会话或恢复现有会话时运行
- SessionEnd:在 Claude Code 会话结束时运行
PreToolUse和PostToolUse匹配器
PreToolUse、PostToolUse常见匹配器:
- Task:子代理任务
- Bash: Shell 命令
- Glob: 文件模式匹配
- Grep:内容搜索
- Read:文件读取
- Edit:编辑
- MultiEdit:多重编辑
- Write:文件写入
- WebFetch:Web拉取
- WebSearch:Web搜索
PreCompact匹配器
PreCompact常见匹配器:
- manual:从 /compact 调用
- auto:从自动压缩调用(由于完整上下文窗口)
SessionStart匹配器
SessionStart常见匹配器:
- startup:从启动调用
- resume:从 –resume、–continue 或 /resume 调用
- clear:从 /clear 调用
- compact:从自动或手动压缩调用
SessionEnd匹配器
SessionEnd常见匹配器:
- clear:使用 /clear 命令清除会话
- logout:用户注销
- prompt_input_exit:用户在提示输入可见时退出
- other:其他退出原因
基本使用
Claude Code CLI提供了创建Hooks的交互式命令,对交互式命令创建Hooks流程还不了解的小伙伴可以看往期内容:Claude Code CLI初体验
在使用示例中我们主要以使用手动配置为主。
读取命令行参数
钩子输入JSON格式可以查看官网文档:https://docs.anthropic.com/en/docs/claude-code/hooks#hook-input
从命令行读取输入参数主要用到jq,简单了解一下jq。
jq是一个轻量级且灵活的命令行 JSON 处理器,它可以对 JSON 数据进行解析、提取、转换和格式化等操作,广泛应用于在 Shell 脚本中处理 JSON 数据,或者在命令行下快速查看和处理 JSON 格式的文件或输出。
jq官网:https://jqlang.org/
以macOS为例,可以使用brew安装jq
在 .claude/settings.local.json添加如下配置:
|
|
重启Claude Code CLI,让Claude Code运行一个简单的命令,比如 ls
执行完成后,可以看到在项目目录下多了一个 bash-command-log.txt文件,内容为 ls - List files in current directory正是Claude Code执行的ls命令及ls命令描述
代码格式化
通过命令行也可以实现代码格式化功能,编辑文件后自动格式化文件,这里以格式化TypeScript文件为例,在 .claude/settings.local.json添加如下配置:
|
|
随便创建一个ts文件,输入示例内容
重启Claude Code CLI,修改ts文件内容
使用 Ctrl+R 快捷键查看详细调用信息,可以看到调了 PostToolUse:Edit钩子并执行了自定义的钩子命令
执行脚本
从前面例子可以看到Shell命令很强大,通过Hooks事件配合Shell命令可以完成很多事件,但是Shell命令自身也有很多局限性,如需要一定学习成本,对于某些复杂和需要灵活定义的场景表现力不从心,不过我们没必要担心,因为Claude Code CLI也支持调用脚本。其次就是使用Shell命令我们无法查看工具调用的输入参数,导致很多脚本基本上都是在盲写,只有通过验证才看到脚本的错误,这些问题通过脚本将不复存在。
执行Shell脚本
在Hooks中使用脚本也很简单,只需要将 command执行内容改成脚本执行方式即可
|
|
在项目根目录创建 hello.sh脚本文件,脚本内容如下:
重启Claude Code CLI,在交互模式随便输入提示词
在Claude Code CLI Hooks事件中也可以使用环境变量 CLAUDE_PROJECT_DIR(仅限于Claude Code CLI Hooks命令中使用) 来引用项目脚本
|
|
执行Python脚本
我们也可以使用Python脚本,修改 settings.local.json 配置如下:
|
|
创建 .claude/hooks/hooks_input.py脚本,注意在Hooks命令中工具调用参数是以标准输入输出方式传递的,使用Python读取参数需要从 sys.stdin中读取
重启Claude Code CLI,在交互模式读取或修改任意文件内容,使用 Ctrl+R快捷键查看详细调用信息
将钩子改为 PostToolUse输出信息如下
执行Ruby脚本
执行Ruby脚本和其他两种脚本方式类似,修改 settings.local.json 配置如下:
|
|
创建.claude/hooks/hooks_input.rb脚本
重启Claude Code CLI,在交互模式读取或修改任意文件内容,使用 Ctrl+R快捷键查看详细调用信息
触发通知
借助Hooks事件和苹果脚本我们可以在需要的时候手动触发系统通知,首先修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,输入任意提示词,就会系统右侧看到通知信息
文件保护
使用脚本可以阻止对敏感文件的编辑,修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,输入任意提示词
当编辑或写入安全目录时就会触发安全拦截阻止文件编辑和写入
敏感提示词过滤
在 .claude/hooks/创建一个 sensitive_prompt.py脚本文件
|
|
代码中输出使用了 “decision”: “block”,官方文档列举了permissionDecision的几种状态值,更详细内容查看官方文档:https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart-decision-control
PreToolUse决策控制:
- allow:绕过权限系统,向用户显示,但不向 Claude 显示(approve已弃用,使用allow代替)
- deny:会阻止工具调用执行,显示给 Claude(block已弃用,使用deny代替)
- ask:要求用户在 UI 中确认工具调用,向用户显示,但不向 Claude 显示
PostToolUse决策控制:
- block:会自动提示 Claude
- undefined:不执行任何作
UserPromptSubmit决策控制:
- block:阻止处理提示,向用户显示,但不会添加到上下文中
- undefined:允许提示正常进行
Stop/SubagentStop决策控制:
- block: 阻止 Claude 停止,必须填充 reason 让 Claude 知道如何继续
- undefined:允许 Claude 停止
修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,输入带有关键词 password 、secret 的提示词就会触发敏感词拦截
不涉及敏感词则打印时间,继续任务
Markdown格式化
该示例功能为自动修复Markdown文件中缺少的语言标记和格式问题,在 .claude/hooks/创建一个 markdown_formatter.py脚本文件
|
|
修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,让AI帮我们创建一个Markdown任务列表,创建完成会触发 PostToolUse:Write钩子
在任务列表添加一个未格式化的代码块
重新让AI添加一些任务项,此时会触发 PostToolUse:Edit钩子
格式化完成后,可以看到代码块也被标记上了指定语言类型
自动批准
在 .claude/hooks/创建一个 auto-approval.py脚本文件,添加脚本内容:
|
|
修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,让AI执行读取文件操作触发 PreToolUse:Read钩子
MCP钩子
在Claude Code CLI中MCP 工具遵循模式 mcp____,例如:
- mcp__filesystem__read_file:文件系统服务器的读取文件工具
- mcp__context7__resolve-library-id:context7获取仓库ID
- mcp__github__search_repositories: GitHub 服务器的搜索工具
修改 settings.local.json 配置如下:
|
|
重启Claude Code CLI,输入提示词
当AI调用context7 MCP工具时就会触发 PreToolUse:mcp__context7__.*钩子
总结
Claude Code CLI提供了功能强大的Hooks事件及反馈机制,开发者可以使用自己熟悉的不同类型脚本来完成自定义Hooks操作,除了示例中的代码格式化、系统通知、文件保护以及敏感词拦截等还可以利用Hooks做更多事情,比如任务完成进行语音提示、任务完成自动触发commit等等都是可以的,场景越多越能感受到SubAgent虽然强大,Hooks才是Claude Code CLI的革命性创新。
友情提示
见原文:Hooks才是Claude Code CLI 的革命性更新
本文同步自微信公众号 “程序员小溪” ,这里只是同步,想看及时消息请移步我的公众号,不定时更新我的学习经验。友情提示友情提示
- 原文作者:知识铺
- 原文链接:https://index.zshipu.com/stock003/post/20251022/Hooks%E6%89%8D%E6%98%AFClaude-Code-CLI-%E7%9A%84%E9%9D%A9%E5%91%BD%E6%80%A7%E6%9B%B4%E6%96%B0/
- 版权声明:本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可,非商业转载请注明出处(作者,原文链接),商业转载请联系作者获得授权。
- 免责声明:本页面内容均来源于站内编辑发布,部分信息来源互联网,并不意味着本站赞同其观点或者证实其内容的真实性,如涉及版权等问题,请立即联系客服进行更改或删除,保证您的合法权益。转载请注明来源,欢迎对文章中的引用来源进行考证,欢迎指出任何有错误或不够清晰的表达。也可以邮件至 sblig@126.com