Otomatisasi alur kerja dengan hooks

​

Siapkan hook pertama Anda

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

notify-send 'Claude Code' 'Claude Code needs your attention'

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

​

Apa yang dapat Anda otomatisasi

• Dapatkan notifikasi ketika Claude memerlukan input
• Format kode otomatis setelah edit
• Blokir edit ke file yang dilindungi
• Injeksi ulang konteks setelah pemadatan
• Audit perubahan konfigurasi

​

Dapatkan notifikasi ketika Claude memerlukan input

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Format kode otomatis setelah edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Blokir edit ke file yang dilindungi

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Injeksi ulang konteks setelah pemadatan

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Audit perubahan konfigurasi

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Cara kerja hooks

• "type": "http": POST data acara ke URL. Lihat HTTP hooks.
• "type": "prompt": evaluasi LLM satu putaran. Lihat Hooks berbasis prompt.
• "type": "agent": verifikasi multi-putaran dengan akses alat. Lihat Hooks berbasis agent.

​

Baca input dan kembalikan output

​

Input hook

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

​

Output hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = let it proceed

• Exit 0: tindakan berlanjut. Untuk hook UserPromptSubmit dan SessionStart, apa pun yang Anda tulis ke stdout ditambahkan ke konteks Claude.
• Exit 2: tindakan diblokir. Tulis alasan ke stderr, dan Claude menerimanya sebagai umpan balik sehingga dapat menyesuaikan.
• Kode keluar lainnya: tindakan berlanjut. Stderr dicatat tetapi tidak ditampilkan ke Claude. Alihkan mode verbose dengan Ctrl+O untuk melihat pesan ini dalam transkrip.

​

Output JSON terstruktur

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": lanjutkan tanpa menampilkan prompt izin
• "deny": batalkan panggilan alat dan kirim alasan ke Claude
• "ask": tampilkan prompt izin kepada pengguna seperti biasa

​

Filter hooks dengan matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Konfigurasi lokasi hook

​

Hooks berbasis prompt

• "ok": true: tindakan berlanjut
• "ok": false: tindakan diblokir. "reason" model diberi umpan balik ke Claude sehingga dapat menyesuaikan.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks berbasis agent

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Batasan dan pemecahan masalah

​

Batasan

• Hooks perintah berkomunikasi melalui stdout, stderr, dan kode keluar saja. Mereka tidak dapat memicu perintah atau panggilan alat secara langsung. HTTP hooks berkomunikasi melalui badan respons sebagai gantinya.
• Timeout hook adalah 10 menit secara default, dapat dikonfigurasi per hook dengan bidang timeout (dalam detik).
• Hook PostToolUse tidak dapat membatalkan tindakan karena alat sudah dieksekusi.
• Hook PermissionRequest tidak aktif dalam mode non-interaktif (-p). Gunakan hooks PreToolUse untuk keputusan izin otomatis.
• Hook Stop aktif kapan pun Claude selesai merespons, bukan hanya saat penyelesaian tugas. Mereka tidak aktif pada interupsi pengguna.

​

Hook tidak aktif

• Jalankan /hooks dan konfirmasi hook muncul di bawah acara yang benar
• Periksa bahwa pola matcher cocok dengan nama alat dengan tepat (matchers peka huruf besar-kecil)
• Verifikasi Anda memicu jenis acara yang benar (misalnya, PreToolUse aktif sebelum eksekusi alat, PostToolUse aktif setelah)
• Jika menggunakan hooks PermissionRequest dalam mode non-interaktif (-p), beralih ke PreToolUse sebagai gantinya

​

Kesalahan hook dalam output

• Skrip Anda keluar dengan kode non-nol secara tidak terduga. Uji secara manual dengan menyalurkan JSON sampel:
  Laporkan kode yang salah

  Salin

  Tanya AI

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Jika Anda melihat “command not found”, gunakan jalur absolut atau $CLAUDE_PROJECT_DIR untuk mereferensikan skrip
• Jika Anda melihat “jq: command not found”, instal jq atau gunakan Python/Node.js untuk penguraian JSON
• Jika skrip tidak berjalan sama sekali, buatnya dapat dieksekusi: chmod +x ./my-hook.sh

​

/hooks menunjukkan tidak ada hooks yang dikonfigurasi

• Mulai ulang sesi Anda atau buka /hooks untuk memuat ulang. Hooks yang ditambahkan melalui menu /hooks berlaku segera, tetapi edit file manual memerlukan reload.
• Verifikasi JSON Anda valid (koma trailing dan komentar tidak diizinkan)
• Konfirmasi file pengaturan berada di lokasi yang benar: .claude/settings.json untuk hooks proyek, ~/.claude/settings.json untuk hooks global

​

Hook Stop berjalan selamanya

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

Validasi JSON gagal

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Teknik debug

​

Pelajari lebih lanjut

• Referensi Hooks: skema acara lengkap, format output JSON, hooks asinkron, dan hooks alat MCP
• Pertimbangan keamanan: tinjau sebelum menerapkan hooks di lingkungan bersama atau produksi
• Contoh validator perintah Bash: implementasi referensi lengkap