~/.claude/settings.json          # 全局配置，所有项目生效
项目/.claude/settings.json       # 项目级配置，团队共享
项目/.claude/settings.local.json # 本地配置，不提交到Git

{
  "session_id": "abc123-def456",
  "transcript_path": "/tmp/claude-session-abc123.jsonl",
  "cwd": "/home/user/my-project",
  "hook_event_name": "PreToolUse"
}

{
  "session_id": "abc123",
  "transcript_path": "/tmp/session.jsonl",
  "cwd": "/home/user/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Clean node_modules"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "不允许删除node_modules，请使用 npm ci 重建"
  }
}

{
  "decision": "block",
  "reason": "危险命令已被拦截"
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/check_bash.py"
          }
        ]
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/check_file_write.py"
          }
        ]
      }
    ]
  }
}

{
  "matcher": "mcp__filesystem__write_file",
  "hooks": [...]
}

#!/usr/bin/env python3
"""PreToolUse Hook: 拦截危险的Bash命令和敏感文件访问"""

import json
import sys
import re
from pathlib import Path


def is_dangerous_rm(command: str) -> bool:
    """检测危险的rm命令模式"""
    normalized = ' '.join(command.lower().split())

    patterns = [
        r'\brm\s+.*-[a-z]*r[a-z]*f',     # rm -rf, rm -fr
        r'\brm\s+--recursive\s+--force',   # 长选项格式
        r'\brm\s+-r\s+.*-f',               # 分开的选项
    ]

    for pattern in patterns:
        if re.search(pattern, normalized):
            return True

    # rm -r 针对危险路径
    dangerous_paths = ['/', '/*', '~', '~/', '$HOME', '*', '.']
    if re.search(r'\brm\s+.*-[a-z]*r', normalized):
        for path in dangerous_paths:
            if re.search(re.escape(path), normalized):
                return True

    return False


def is_protected_file(tool_name: str, tool_input: dict) -> bool:
    """检查是否访问受保护的文件"""
    protected = ['.env', '.env.production', '.env.staging']

    if tool_name in ('Read', 'Edit', 'Write', 'MultiEdit'):
        file_path = tool_input.get('file_path', '')
        for p in protected:
            if p in file_path and not file_path.endswith('.env.sample'):
                return True

    return False


def main():
    try:
        data = json.load(sys.stdin)
        tool_name = data.get('tool_name', '')
        tool_input = data.get('tool_input', {})

        # 检查受保护文件
        if is_protected_file(tool_name, tool_input):
            msg = json.dumps({
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason":
                        "受保护的.env文件不可修改，请使用.env.sample作为模板"
                }
            })
            print(msg)
            sys.exit(0)

        # 检查危险Bash命令
        if tool_name == 'Bash':
            command = tool_input.get('command', '')
            if is_dangerous_rm(command):
                msg = json.dumps({
                    "hookSpecificOutput": {
                        "hookEventName": "PreToolUse",
                        "permissionDecision": "deny",
                        "permissionDecisionReason":
                            f"检测到危险删除命令: '{command[:80]}'。已被安全策略拦截。"
                    }
                })
                print(msg)
                sys.exit(0)

        sys.exit(0)  # 放行

    except Exception:
        sys.exit(0)  # 异常时放行，不阻塞工作流


if __name__ == '__main__':
    main()

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_tool_use.py"
          }
        ]
      }
    ]
  }
}

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/home/user/project/src/app.tsx",
    "content": "export default function App() { return <div>Hello</div> }"
  },
  "tool_response": {
    "success": true
  }
}

#!/usr/bin/env python3
"""PostToolUse Hook: 自动格式化编辑过的文件"""

import json
import sys
import subprocess
from pathlib import Path


# 需要自动格式化的文件扩展名和对应命令
FORMATTERS = {
    '.ts': 'npx prettier --write {path}',
    '.tsx': 'npx prettier --write {path}',
    '.js': 'npx prettier --write {path}',
    '.jsx': 'npx prettier --write {path}',
    '.css': 'npx prettier --write {path}',
    '.json': 'npx prettier --write {path}',
    '.py': 'python3 -m black {path}',
    '.go': 'gofmt -w {path}',
    '.rs': 'rustfmt {path}',
}


def should_format(tool_name: str, tool_input: dict) -> str | None:
    """判断是否需要格式化，返回文件路径或None"""
    if tool_name not in ('Write', 'Edit', 'MultiEdit'):
        return None

    file_path = tool_input.get('file_path', '')
    suffix = Path(file_path).suffix

    if suffix in FORMATTERS:
        return file_path
    return None


def main():
    try:
        data = json.load(sys.stdin)
        tool_name = data.get('tool_name', '')
        tool_input = data.get('tool_input', {})

        file_path = should_format(tool_name, tool_input)
        if not file_path:
            sys.exit(0)

        suffix = Path(file_path).suffix
        cmd = FORMATTERS[suffix].format(path=file_path)

        result = subprocess.run(
            cmd, shell=True, capture_output=True, text=True, timeout=30
        )

        if result.returncode == 0:
            # 格式化成功，给Claude一个反馈
            output = json.dumps({
                "decision": None,
                "reason": f"已自动格式化 {file_path}"
            })
            print(output)
        else:
            # 格式化失败，让Claude知道
            output = json.dumps({
                "decision": "block",
                "reason": f"格式化失败: {result.stderr[:200]}"
            })
            print(output)

        sys.exit(0)

    except Exception as e:
        print(f"格式化hook异常: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == '__main__':
    main()

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/auto_format.py"
          }
        ]
      }
    ]
  }
}

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "帮我删除所有node_modules文件夹"
}

#!/usr/bin/env python3
"""UserPromptSubmit Hook: 自动注入当前分支和最近改动信息"""

import json
import sys
import subprocess


def get_git_context() -> str:
    """获取Git仓库当前状态"""
    parts = []

    # 当前分支
    result = subprocess.run(
        ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
        capture_output=True, text=True, timeout=5
    )
    if result.returncode == 0:
        branch = result.stdout.strip()
        parts.append(f"当前Git分支: {branch}")

    # 未提交的改动数量
    result = subprocess.run(
        ['git', 'status', '--porcelain'],
        capture_output=True, text=True, timeout=5
    )
    if result.returncode == 0:
        changes = [l for l in result.stdout.strip().split('\n') if l]
        if changes:
            parts.append(f"未提交的文件改动: {len(changes)}个")
            # 列出前5个改动文件
            for change in changes[:5]:
                parts.append(f"  {change}")

    # 最近3条commit
    result = subprocess.run(
        ['git', 'log', '--oneline', '-3'],
        capture_output=True, text=True, timeout=5
    )
    if result.returncode == 0 and result.stdout.strip():
        parts.append("最近提交:")
        for line in result.stdout.strip().split('\n'):
            parts.append(f"  {line}")

    return '\n'.join(parts) if parts else ""


def main():
    try:
        data = json.load(sys.stdin)
        prompt = data.get('prompt', '')

        # 检测到关键词时注入额外上下文
        keywords = ['提交', 'commit', '发布', 'deploy', 'push', '测试', 'test']
        should_inject = any(kw in prompt.lower() for kw in keywords)

        if should_inject:
            context = get_git_context()
            if context:
                # stdout内容会被注入到上下文
                print(f"\n[自动上下文]\n{context}\n")

        sys.exit(0)

    except Exception:
        sys.exit(0)


if __name__ == '__main__':
    main()

{
  "session_id": "abc123",
  "hook_event_name": "SessionStart",
  "source": "startup",   // "startup" | "resume" | "clear"
  "cwd": "/home/user/project"
}

#!/usr/bin/env python3
"""SessionStart Hook: 根据项目结构自动注入引导信息"""

import json
import sys
from pathlib import Path


def detect_project_type(cwd: str) -> dict:
    """检测项目类型和关键信息"""
    root = Path(cwd)
    info = {"type": "unknown", "tips": []}

    # Node.js / React 项目
    if (root / 'package.json').exists():
        info["type"] = "node"
        pkg = json.loads((root / 'package.json').read_text())
        info["name"] = pkg.get('name', 'unknown')

        scripts = pkg.get('scripts', {})
        if 'test' in scripts:
            info["tips"].append(f"测试命令: npm test ({scripts['test']})")
        if 'build' in scripts:
            info["tips"].append(f"构建命令: npm run build ({scripts['build']})")
        if 'lint' in scripts:
            info["tips"].append(f"代码检查: npm run lint ({scripts['lint']})")

        deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
        if 'react' in deps:
            info["framework"] = f"React {deps['react']}"
        if 'next' in deps:
            info["framework"] = f"Next.js {deps['next']}"
        if 'vue' in deps:
            info["framework"] = f"Vue {deps['vue']}"

    # Python 项目
    elif (root / 'pyproject.toml').exists() or (root / 'setup.py').exists():
        info["type"] = "python"
        if (root / 'pyproject.toml').exists():
            info["tips"].append("使用 uv 管理依赖")
        if (root / 'pytest.ini').exists() or (root / 'conftest.py').exists():
            info["tips"].append("测试命令: pytest")

    # Go 项目
    elif (root / 'go.mod').exists():
        info["type"] = "go"
        info["tips"].extend([
            "构建: go build ./...",
            "测试: go test ./...",
            "格式化: gofmt -w ."
        ])

    # Rust 项目
    elif (root / 'Cargo.toml').exists():
        info["type"] = "rust"
        info["tips"].extend([
            "构建: cargo build",
            "测试: cargo test",
            "格式化: cargo fmt"
        ])

    # 检测CLAUDE.md
    if (root / 'CLAUDE.md').exists():
        info["tips"].append("已检测到CLAUDE.md项目配置文件")

    return info


def main():
    try:
        data = json.load(sys.stdin)
        cwd = data.get('cwd', '.')
        source = data.get('source', 'startup')

        if source == 'startup':
            info = detect_project_type(cwd)

            lines = ["[项目自动识别]"]
            lines.append(f"项目类型: {info['type']}")

            if 'framework' in info:
                lines.append(f"框架: {info['framework']}")
            if 'name' in info:
                lines.append(f"项目名: {info['name']}")

            if info['tips']:
                lines.append("可用命令:")
                for tip in info['tips']:
                    lines.append(f"  - {tip}")

            print('\n'.join(lines))

        sys.exit(0)

    except Exception:
        sys.exit(0)


if __name__ == '__main__':
    main()

{
  "session_id": "abc123",
  "hook_event_name": "Stop",
  "stop_hook_active": false
}

#!/usr/bin/env python3
"""Stop Hook: 确保所有改动通过lint和测试后才允许结束"""

import json
import sys
import subprocess
from pathlib import Path


def has_uncommitted_changes() -> bool:
    result = subprocess.run(
        ['git', 'diff', '--exit-code'],
        capture_output=True, timeout=10
    )
    return result.returncode != 0


def run_lint() -> tuple[bool, str]:
    """运行lint检查"""
    root = Path.cwd()

    if (root / 'package.json').exists():
        result = subprocess.run(
            ['npx', 'eslint', '.', '--max-warnings=0'],
            capture_output=True, text=True, timeout=60
        )
        if result.returncode != 0:
            return False, result.stdout + result.stderr

    if (root / 'pyproject.toml').exists():
        result = subprocess.run(
            ['python3', '-m', 'ruff', 'check', '.'],
            capture_output=True, text=True, timeout=60
        )
        if result.returncode != 0:
            return False, result.stdout + result.stderr

    return True, ""


def run_tests() -> tuple[bool, str]:
    """运行测试"""
    root = Path.cwd()

    if (root / 'package.json').exists():
        result = subprocess.run(
            ['npm', 'test'], capture_output=True, text=True, timeout=120
        )
        if result.returncode != 0:
            return False, result.stdout[-500:]  # 最后500字符

    return True, ""


def main():
    try:
        data = json.load(sys.stdin)

        if not has_uncommitted_changes():
            sys.exit(0)  # 没有改动，直接放行

        # 有未提交改动，执行检查
        lint_ok, lint_err = run_lint()
        if not lint_ok:
            output = json.dumps({
                "decision": "block",
                "reason": f"代码Lint检查未通过，请修复后再完成:\n{lint_err[:500]}"
            })
            print(output)
            sys.exit(0)

        test_ok, test_err = run_tests()
        if not test_ok:
            output = json.dumps({
                "decision": "block",
                "reason": f"测试未通过，请修复后再完成:\n{test_err[:500]}"
            })
            print(output)
            sys.exit(0)

        sys.exit(0)  # 全部通过

    except Exception:
        sys.exit(0)


if __name__ == '__main__':
    main()

#!/usr/bin/env python3
"""Notification Hook: 发送桌面通知"""

import json
import sys
import subprocess
import os


def send_desktop_notification(message: str):
    """发送桌面通知（Linux/macOS）"""
    if sys.platform == 'darwin':
        # macOS: 使用osascript
        script = f'display notification "{message}" with title "Claude Code"'
        subprocess.run(['osascript', '-e', script], timeout=5)
    else:
        # Linux: 使用notify-send
        subprocess.run(
            ['notify-send', 'Claude Code', message, '-t', '5000'],
            timeout=5
        )


def main():
    try:
        data = json.load(sys.stdin)
        message = data.get('message', '需要你的关注')
        send_desktop_notification(message)
        sys.exit(0)
    except Exception:
        sys.exit(0)


if __name__ == '__main__':
    main()

#!/usr/bin/env python3
"""PreCompact Hook: 备份压缩前的对话记录"""

import json
import sys
import shutil
from pathlib import Path
from datetime import datetime


def main():
    try:
        data = json.load(sys.stdin)
        transcript_path = data.get('transcript_path', '')
        trigger = data.get('trigger', 'unknown')

        if transcript_path and Path(transcript_path).exists():
            # 创建备份目录
            backup_dir = Path('logs') / 'transcript_backups'
            backup_dir.mkdir(parents=True, exist_ok=True)

            # 生成带时间戳的备份文件名
            ts = datetime.now().strftime('%Y%m%d_%H%M%S')
            session = Path(transcript_path).stem
            backup = backup_dir / f"{session}_pre_compact_{trigger}_{ts}.jsonl"

            shutil.copy2(transcript_path, backup)

        sys.exit(0)
    except Exception:
        sys.exit(0)


if __name__ == '__main__':
    main()

my-project/
├── .claude/
│   ├── settings.json          # Hooks注册配置
│   ├── hooks/
│   │   ├── pre_tool_use.py    # 安全护栏
│   │   ├── post_tool_use.py   # 自动格式化
│   │   ├── user_prompt.py     # Prompt预处理
│   │   ├── session_start.py   # 会话引导
│   │   ├── stop.py            # 完成检查
│   │   ├── notification.py    # 桌面通知
│   │   └── pre_compact.py     # 上下文备份
│   └── data/
│       └── sessions/          # 会话数据存储
├── logs/                      # 审计日志（gitignore）
│   └── .gitkeep
└── .gitignore

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "Bash(npx:*)",
      "Bash(python3:*)",
      "Bash(pytest:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": []
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/session_start.py"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_tool_use.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/post_tool_use.py"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/user_prompt.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/stop.py"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/notification.py"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/pre_compact.py"
          }
        ]
      }
    ]
  }
}

# 查看生效的settings配置
cat .claude/settings.json | python3 -m json.tool

# 模拟PreToolUse输入
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | \
  python3 .claude/hooks/pre_tool_use.py
echo "Exit code: $?"

import datetime

def log(msg: str):
    with open('logs/hooks_debug.log', 'a') as f:
        ts = datetime.datetime.now().isoformat()
        f.write(f"[{ts}] {msg}\n")

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "python-dotenv",
#     "requests",
# ]
# ///

import requests
# ... 正常代码

{
  "type": "command",
  "command": "uv run .claude/hooks/notification.py"
}

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {"type": "command", "command": "python3 .claude/hooks/check_bash.py"}
      ]
    },
    {
      "matcher": "Write|Edit",
      "hooks": [
        {"type": "command", "command": "python3 .claude/hooks/check_file_write.py"}
      ]
    },
    {
      "matcher": "",
      "hooks": [
        {"type": "command", "command": "python3 .claude/hooks/log_all_tools.py"}
      ]
    }
  ]
}

#!/usr/bin/env python3
import os

# 通过环境变量控制是否启用某个hook
ENABLE_STRICT_MODE = os.getenv('CLAUDE_HOOK_STRICT', 'false') == 'true'
ENABLE_NOTIFICATIONS = os.getenv('CLAUDE_HOOK_NOTIFY', 'true') == 'true'

if not ENABLE_STRICT_MODE:
    sys.exit(0)  # 跳过检查

export CLAUDE_HOOK_STRICT=true    # 严格模式
export CLAUDE_HOOK_NOTIFY=true    # 开启通知

{
  "type": "http",
  "url": "https://your-server.com/api/clause-hook"
}

{
  "type": "llm",
  "prompt": "分析这个Bash命令是否安全。如果涉及rm、curl pipe bash、sudo等危险操作，返回BLOCKED。"
}