Claude Code Hooks
了解 Hook 事件、复制小型示例，并检查命令执行风险。
当前收录 15 个精选条目
可复制的 Hook 示例
什么是 Claude Code Hooks
Claude Code Hook 会响应工具调用、提交提示词或开始会话等生命周期事件。根据类型，它可以执行命令、请求模型检查条件，或提供上下文。Hooks 很适合重复检查，但其行为和权限必须明确。
Hook 适合触发条件明确的工作：检查待执行工具请求、开始会话时提供项目提示、编辑文件后补充检查要求。先写清事件与预期结果；单纯复用任务说明时，Skill 或 Command 更易维护。
本页讲设置型 Hooks。原生 Mods 的函数钩子运行于 Claude Code 内部，注册格式不同，不应把 JavaScript 模块直接粘贴到设置 JSON。下方示例应合并到 hooks 字段，并保留其他配置和已有事件。
Hook 事件说明
PreToolUse 在匹配工具执行前触发，适合防护与批准检查；PostToolUse 在执行后触发，可检查结果；SessionStart 准备上下文；UserPromptSubmit 可响应新提示词。应选择最窄的事件和匹配器，避免无关执行。
四个示例对应会话的不同阶段：执行前确认、成功执行后补充上下文、会话开始时提供信息，以及处理提示词前补充提醒。它们是事件钩子，不是定时器或后台同步服务。
Matcher 匹配事件特定的值，而不是任意对话文本。工具事件中的 Edit|Write 匹配工具名称，SessionStart 的 startup 匹配新会话；UserPromptSubmit 不支持 Matcher，因此示例省略该字段。
PreToolUse
在 Bash 工具执行前请求确认。正常权限流程继续参与判断；这不是判断命令是否安全的检测器。每次匹配都会询问，因此先在测试项目试用，避免给日常工作增加过多提示。
PreToolUse · .claude/settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Confirm this shell command before it runs.\"}}'"
}
]
}
]
}
}PostToolUse
Edit 或 Write 成功后，为 Claude 补充选择相关检查的提示。此时文件已经改变；这个 Hook 不会撤销修改，也不会自动运行测试，最终应检查实际测试结果。
PostToolUse · .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"A file changed. Choose the relevant checks before reporting completion.\"}}'"
}
]
}
]
}
}SessionStart
startup 匹配新会话，输出项目使用 pnpm 的约定。请替换成真实项目要求；它不会安装依赖，也不会修改设置。该 Matcher 不覆盖恢复会话或压缩上下文。
SessionStart · .claude/settings.json
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "printf '%s\\n' 'Project convention: use pnpm and check package.json for available scripts.'"
}
]
}
]
}
}UserPromptSubmit
在处理提交的提示词前补充输出约定，不使用 Matcher。频繁触发时重复上下文也有成本；保持简短，不把私密信息写进输出。普通任务说明也可以放进 Skill。
UserPromptSubmit · .claude/settings.json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "printf '%s\\n' 'When describing a change, include its file path and verification result.'"
}
]
}
]
}
}安全提示：Hooks 可以运行 Shell 命令
命令型 Hook 可在 Claude Code 进程的权限范围内执行 Shell 命令。看似普通的检查也可能读取文件、改动仓库或访问网络。启用前请查看脚本、路径、环境变量和插件更新。下方说明仅介绍能力，不等于正式安全审计。
事件数据应作为输入处理，不能当作 Shell 源码。文件名和提示词可能包含引号、空格或命令语法；应解析 JSON、引用参数并避免 eval。这里的示例只输出固定文本或 JSON，不把用户输入拼进可执行命令。
若每个事件都启动网络请求或完整测试，普通编辑也会变慢。先用范围较窄的 Matcher 和简短本地动作；后续接入格式化工具时，确认目标文件正确，重复运行不会产生循环或无关修改。
不要把密钥写入上下文或调试日志。先在测试项目试运行，再审查配置差异。删除 Hook 只会停止后续调用，不能撤销之前脚本已进行的写入或请求。
Security Guidance
Hooks 可执行命令并检查代码；启用前请阅读插件说明。
Hookify
规则会检查提示词或工具调用；启用前请检查匹配模式。
Explanatory Output Style
SessionStart Hook 会在会话开始时自动执行。
Dangerous Command Guard
启用前核对该 Hook 的事件与执行权限。
Sensitive File Guard
启用前核对该 Hook 的事件与执行权限。
Git Safety Hook
启用前核对该 Hook 的事件与执行权限。
Test Preservation Hook
启用前核对该 Hook 的事件与执行权限。
Auto Stage Hook
启用前核对该 Hook 的事件与执行权限。
Format Code Hook
启用前核对该 Hook 的事件与执行权限。
Slack Permission Notifications
启用前核对该 Hook 的事件与执行权限。
Session Markdown Logger
启用前核对该 Hook 的事件与执行权限。
Context Hogs
启用前核对该 Hook 的事件与执行权限。
Standup Autopilot
启用前核对该 Hook 的事件与执行权限。
Configuration Watch Hook
启用前核对该 Hook 的事件与执行权限。
Dead End Registry
启用前核对该 Hook 的事件与执行权限。
如何编写自己的 Hook
从一个事件、一个匹配器和一个小动作开始。项目级配置可放在 `.claude/settings.json`，并说明 Hook 的目的。分别验证成功和失败时的行为，再按需扩展，避免给团队成员带来意外。
选取上方一个示例，把 hooks 内容合并到 .claude/settings.json，不要覆盖已有权限和其他钩子。这些示例使用 POSIX Shell；Windows 需要兼容环境或改写为 PowerShell。示例不依赖外部包，也不写入文件。
打开 /hooks 检查加载状态，再在测试项目触发事件。Bash 示例应请求确认，编辑示例应在成功编辑后补充指令。提醒不会自动运行测试；JSON 格式正确也不代表工作流已经验证完成。
也应测试不匹配的情况：Read 不应触发 Edit|Write 钩子。诊断输出要与标准输出上的 JSON 分开；行为不符时先缩减到一个事件，查看 Hook 诊断，再逐步增加逻辑。
Claude Code 官方参考文档常见问题
什么是 Claude Code Mod？
Mod 是通过 JavaScript 或 TypeScript 函数钩子在 Claude Code 内部运行的插件，可以改变界面或会话事件的处理方式。Skills 和 MCP Servers 属于不同的扩展类型。
这些项目都是官方的吗？
本站是独立目录，部分条目来自 Anthropic 仓库，其他来自社区维护者。安装前请查看每条项目的来源。
安装 Mods 安全吗？
扩展可能读取文件、执行命令或连接外部服务。请检查来源和权限，尤其是 Hooks 与 MCP Servers。本站收录不构成安全保证。
星数和日期代表什么？
它们是来源 GitHub 仓库的数据。仓库内的单个插件通常没有独立星数或更新时间。