Claude Code Hook 使用指南

📁 当前可用的 Hooks

1. hello.py - 原始 Hook

• 功能: 基础的项目状态检测
• 用途: 向 AI 传递项目上下文信息

2. welcome.py - 欢迎信息 Hook ⭐

• 功能: 显示彩色的欢迎信息
• 内容包括:
  • 用户名
  • 当前时间
  • 工作目录
  • Git 分支
  • Git 工作目录状态
• 特点: 美观的彩色输出

3. system_info.py - 系统信息 Hook ⭐

• 功能: 显示详细的系统和项目统计
• 内容包括:
  • 操作系统信息
  • Python 版本
  • 项目文件统计（Python/JS/TS/Markdown 文件数）
  • Git 仓库统计（提交数、分支数、最新提交）
• 特点: 详细的项目概览

🔧 如何使用

选择要启用的 Hook

在 .claude/settings.json 中配置（如果不存在则创建）：

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "python ~/.claude/hooks/welcome.py"
      }
    ]
  }
}

或者使用多个 Hook：

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "python ~/.claude/hooks/welcome.py"
      },
      {
        "type": "command",
        "command": "python ~/.claude/hooks/system_info.py"
      }
    ]
  }
}

在 Windows 上路径

Windows 上使用：

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "python C:\\Users\\starm\\.claude\\hooks\\welcome.py"
      }
    ]
  }
}

📝 Hook 工作原理

输入格式

Hook 通过 stdin 接收 JSON 格式的输入数据。

输出格式

Hook 必须输出 JSON 格式的数据：

output = {
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": "传递给 AI 的上下文信息"
    }
}
print(json.dumps(output))

显示内容给用户

有两种方式显示内容给终端用户：

方式 1: 输出到 stderr

print("这是显示给用户的信息", file=sys.stderr)

方式 2: 返回消息

output = {
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "message": "显示给用户的消息",
        "additionalContext": "传递给 AI 的上下文"
    }
}

🎨 自定义你的 Hook

修改显示内容

编辑 Hook 文件，自定义要显示的信息：

# 在 welcome.py 或 system_info.py 中修改
def display_custom_info():
    print(f"{GREEN}自定义内容:{END} 你的信息", file=sys.stderr)

添加新的检测

# 检测项目类型
if os.path.exists("package.json"):
    project_type = "Node.js"
elif os.path.exists("Cargo.toml"):
    project_type = "Rust"
# 添加更多检测...

📊 可用的 Hook 事件

事件	触发时机	用途
SessionStart	会话开始	显示欢迎信息、系统信息
PreToolUse	工具使用前	验证、阻止操作
PostToolUse	工具使用后	格式化、测试
Notification	通知发生	发送提醒

🚨 注意事项

1. JSON 输出必须有效: Hook 必须输出有效的 JSON，否则会失败
2. 使用 stderr 显示信息: 终端输出应该使用 stderr，避免干扰 JSON 返回值
3. 错误处理: 添加适当的异常处理，避免 Hook 崩溃
4. 性能: Hook 会影响启动速度，保持轻量级

🎯 示例：创建自定义 Hook

#!/usr/bin/env python3
import json
import sys
import os

def main():
    # 加载输入
    try:
        input_data = json.load(sys.stdin)
    except json.JSONDecodeError:
        sys.exit(1)

    # 显示自定义信息
    print("🎨 我的自定义 Hook", file=sys.stderr)

    # 返回输出
    output = {
        "hookSpecificOutput": {
            "hookEventName": "SessionStart",
            "additionalContext": "传递给 AI 的信息"
        }
    }
    print(json.dumps(output))

if __name__ == "__main__":
    main()

🔍 调试 Hook

测试 Hook 是否工作：

# 直接运行 Hook（需要提供 JSON 输入）
echo '{}' | python ~/.claude/hooks/welcome.py

查看 Hook 日志（如果有）：

# 检查 Claude Code 日志
cat ~/.claude/logs/*.log

📚 更多资源

• Claude Code 官方文档
• Hook 配置参考
• 社区 Hook 示例