Hooks

Hook 是什么

Hook = 事件 + 匹配条件 + shell 命令。

当某个事件触发(比如 PostToolUse),Claude 会按你写的匹配条件执行对应的 shell 命令。命令的 stdout / 退出码可以影响 Claude 后续行为(比如阻止某个操作)。

典型用途:

• 写完 .ts 文件自动 prettier --write
• Bash 调用前阻止 rm -rf / 这种危险命令
• 会话结束发桌面通知
• 自动把改动的文件 git add

配置位置

写在 settings.json,三个层级:

• ~/.claude/settings.json —— 全局
• <project>/.claude/settings.json —— 项目共享(进 git)
• <project>/.claude/settings.local.json —— 项目个人(不进 git)

格式:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": {
          "tool": "Write",
          "path": ".*\\.ts$"
        },
        "command": "npx prettier --write $CLAUDE_PATH"
      }
    ]
  }
}

可用事件

| 事件 | 时机 | 典型用途 | | --- | --- | --- | | PreToolUse | 工具调用前 | 阻止危险操作、做条件校验 | | PostToolUse | 工具调用后 | 自动格式化、自动 git add | | UserPromptSubmit | 用户提交消息时 | 注入额外上下文 | | Stop | 会话停止时 | 发通知、清理临时文件 | | Notification | Claude 发通知时 | 转发到桌面通知 / IM |

匹配字段(matcher):

• tool —— 工具名,支持正则,如 "Bash"、"Edit|Write"
• path —— 涉及的文件路径,正则匹配
• command —— Bash 工具的命令文本,正则匹配

实战示例

示例 1:写 TS 文件自动 prettier

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": { "tool": "Write|Edit", "path": ".*\\.(ts|tsx|js|jsx)$" },
        "command": "npx prettier --write \"$CLAUDE_PATH\" 2>&1 | tail -3"
      }
    ]
  }
}

环境变量 $CLAUDE_PATH 是当前操作的文件路径。

示例 2:阻止危险 Bash

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": { "tool": "Bash", "command": "rm\\s+-rf\\s+/" },
        "command": "echo 'BLOCKED: rm -rf /' >&2; exit 2"
      }
    ]
  }
}

退出码 2 会阻止该次工具调用,Claude 收到 stderr 后会换思路。

示例 3:每次写文件自动 git add

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": { "tool": "Write|Edit" },
        "command": "git add \"$CLAUDE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

注意末尾的 || true —— 文件不在 git 仓库时会失败,加这个避免影响 Claude。

示例 4:会话结束发桌面通知

{
  "hooks": {
    "Stop": [
      {
        "command": "osascript -e 'display notification \"Claude 完成任务\" with title \"Claude Code\"'"
      }
    ]
  }
}

macOS 用 osascript;Linux 用 notify-send;WSL 用 powershell.exe -c \"...\"。

实用技巧

1. 调试时打开 trace

启动 Claude 时加 --verbose,可以看到 hook 的命令、stdout、stderr、退出码 —— 排错最快的方式。

2. hook 不要做重活

hook 是同步的,会阻塞 Claude。如果要跑测试这种慢任务,要么放到后台(&),要么改成"提示+建议"而非"强制等待"。

3. 用 update-config skill 改 settings

直接说"加一个 hook,在写 ts 文件时自动 prettier",Claude 会用 update-config skill 帮你修改 settings.json,不用自己手写 JSON。

4. 项目共享 vs 个人

把团队规范(自动 format)放 settings.json 进 git;把个人偏好(桌面通知)放 settings.local.json,这样队友不会被你的通知打扰。

回到 示例列表 →