跳轉到主要內容
Claude Code 鉤子是使用者定義的 shell 命令，在 Claude Code 生命週期的各個點執行。鉤子提供對 Claude Code 行為的確定性控制，確保某些操作總是發生，而不是依賴 LLM 選擇執行它們。
如需鉤子的參考文件，請參閱鉤子參考。
鉤子的範例使用案例包括：
  • 通知：自訂當 Claude Code 等待您的輸入或執行某些操作的權限時如何通知您。
  • 自動格式化：在每次檔案編輯後，在 .ts 檔案上執行 prettier、在 .go 檔案上執行 gofmt 等。
  • 日誌記錄：追蹤和計算所有執行的命令以進行合規性或除錯。
  • 回饋：當 Claude Code 產生不遵循您的程式碼庫慣例的程式碼時提供自動回饋。
  • 自訂權限：阻止對生產檔案或敏感目錄的修改。
透過將這些規則編碼為鉤子而不是提示指令，您將建議轉變為應用程式級程式碼，每次預期執行時都會執行。
當您新增鉤子時，必須考慮鉤子的安全含義，因為鉤子在代理迴圈期間使用您目前環境的認證自動執行。例如，惡意鉤子程式碼可以洩露您的資料。在註冊鉤子之前，請務必檢查您的鉤子實作。如需完整的安全最佳實踐，請參閱鉤子參考文件中的安全考慮。

​
鉤子事件概述

Claude Code 提供多個鉤子事件，在工作流程的不同點執行：
  • PreToolUse：在工具呼叫之前執行（可以阻止它們）
  • PostToolUse：在工具呼叫完成後執行
  • UserPromptSubmit：當使用者提交提示時執行，在 Claude 處理之前
  • Notification：當 Claude Code 傳送通知時執行
  • Stop：當 Claude Code 完成回應時執行
  • SubagentStop：當子代理任務完成時執行
  • PreCompact：在 Claude Code 即將執行壓縮操作之前執行
  • SessionStart：當 Claude Code 啟動新工作階段或繼續現有工作階段時執行
  • SessionEnd：當 Claude Code 工作階段結束時執行
每個事件接收不同的資料，並可以以不同的方式控制 Claude 的行為。

​
快速入門

在此快速入門中，您將新增一個鉤子來記錄 Claude Code 執行的 shell 命令。

​
先決條件

安裝 jq 以在命令列中進行 JSON 處理。

​
步驟 1：開啟鉤子設定

執行 /hooks斜線命令並選擇 PreToolUse 鉤子事件。 PreToolUse 鉤子在工具呼叫之前執行，可以阻止它們，同時向 Claude 提供有關如何執行不同操作的回饋。

​
步驟 2：新增匹配器

選擇 + Add new matcher… 以僅在 Bash 工具呼叫上執行您的鉤子。 為匹配器輸入 Bash。
您可以使用 * 來匹配所有工具。

​
步驟 3：新增鉤子

選擇 + Add new hook… 並輸入此命令： 
jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
步驟 4：儲存您的設定

對於儲存位置，選擇 User settings，因為您正在記錄到您的主目錄。此鉤子將適用於所有專案，而不僅僅是您目前的專案。 然後按 Esc 直到您返回 REPL。您的鉤子現已註冊！

​
步驟 5：驗證您的鉤子

再次執行 /hooks 或檢查 ~/.claude/settings.json 以查看您的設定： 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
步驟 6：測試您的鉤子

要求 Claude 執行簡單命令（如 ls）並檢查您的日誌檔案： 
cat ~/.claude/bash-command-log.txt
您應該看到類似的項目： 
ls - Lists files and directories

​
更多範例

如需完整的範例實作，請參閱我們公開程式碼庫中的 bash 命令驗證器範例。

​
程式碼格式化鉤子

編輯後自動格式化 TypeScript 檔案： 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

​
Markdown 格式化鉤子

自動修復 markdown 檔案中遺失的語言標籤和格式化問題： 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
          }
        ]
      }
    ]
  }
}
使用此內容建立 .claude/hooks/markdown_formatter.py： 
#!/usr/bin/env python3
"""
Markdown formatter for Claude Code output.
Fixes missing language tags and spacing issues while preserving code content.
"""
import json
import sys
import re
import os

def detect_language(code):
    """Best-effort language detection from code content."""
    s = code.strip()
    
    # JSON detection
    if re.search(r'^\s*[{\[]', s):
        try:
            json.loads(s)
            return 'json'
        except:
            pass
    
    # Python detection
    if re.search(r'^\s*def\s+\w+\s*\(', s, re.M) or \
       re.search(r'^\s*(import|from)\s+\w+', s, re.M):
        return 'python'
    
    # JavaScript detection  
    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', s) or \
       re.search(r'=>|console\.(log|error)', s):
        return 'javascript'
    
    # Bash detection
    if re.search(r'^#!.*\b(bash|sh)\b', s, re.M) or \
       re.search(r'\b(if|then|fi|for|in|do|done)\b', s):
        return 'bash'
    
    # SQL detection
    if re.search(r'\b(SELECT|INSERT|UPDATE|DELETE|CREATE)\s+', s, re.I):
        return 'sql'
        
    return 'text'

def format_markdown(content):
    """Format markdown content with language detection."""
    # Fix unlabeled code fences
    def add_lang_to_fence(match):
        indent, info, body, closing = match.groups()
        if not info.strip():
            lang = detect_language(body)
            return f"{indent}```{lang}\n{body}{closing}\n"
        return match.group(0)
    
    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
    content = re.sub(fence_pattern, add_lang_to_fence, content)
    
    # Fix excessive blank lines (only outside code fences)
    content = re.sub(r'\n{3,}', '\n\n', content)
    
    return content.rstrip() + '\n'

# Main execution
try:
    input_data = json.load(sys.stdin)
    file_path = input_data.get('tool_input', {}).get('file_path', '')
    
    if not file_path.endswith(('.md', '.mdx')):
        sys.exit(0)  # Not a markdown file
    
    if os.path.exists(file_path):
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        
        formatted = format_markdown(content)
        
        if formatted != content:
            with open(file_path, 'w', encoding='utf-8') as f:
                f.write(formatted)
            print(f"✓ Fixed markdown formatting in {file_path}")
    
except Exception as e:
    print(f"Error formatting markdown: {e}", file=sys.stderr)
    sys.exit(1)
使指令碼可執行： 
chmod +x .claude/hooks/markdown_formatter.py
此鉤子自動：
  • 偵測未標記程式碼區塊中的程式設計語言
  • 為語法突出顯示新增適當的語言標籤
  • 修復過度的空白行，同時保留程式碼內容
  • 僅處理 markdown 檔案（.md、.mdx）

​
自訂通知鉤子

當 Claude 需要輸入時取得桌面通知： 
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

​
檔案保護鉤子

阻止編輯敏感檔案： 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​
深入瞭解

  • 如需鉤子的參考文件，請參閱鉤子參考。
  • 如需全面的安全最佳實踐和安全指南，請參閱鉤子參考文件中的安全考慮。
  • 如需故障排除步驟和除錯技術，請參閱鉤子參考文件中的除錯。