Otomatisasi tindakan dengan hooks

​

Siapkan hook pertama Anda

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Apa yang dapat Anda otomatisasi

​

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\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

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

notify-send 'Claude Code' 'test'

{
  "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')\""
          }
        ]
      }
    ]
  }
}

​

Auto-format kode 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')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

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"
          }
        ]
      }
    ]
  }
}

​

Re-inject konteks setelah compaction

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Muat ulang lingkungan ketika direktori atau file berubah

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Auto-approve prompt izin tertentu

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Cara kerja hooks

• "type": "http": POST data acara ke URL. Lihat HTTP hooks.
• "type": "mcp_tool": panggil alat pada server MCP yang sudah terhubung. Lihat MCP tool hooks.
• "type": "prompt": evaluasi LLM single-turn. Lihat Prompt-based hooks.
• "type": "agent": verifikasi multi-turn dengan akses alat. Agent hooks bersifat eksperimental dan mungkin berubah. Lihat Agent-based hooks.

​

Gabungkan hasil dari beberapa hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Baca input dan kembalikan output

​

Hook input

• hook_event_name: acara yang memicu hook
• tool_name: alat yang akan digunakan Claude
• tool_input: argumen yang Claude teruskan ke alat. Untuk Bash, bidang command menyimpan perintah shell.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Hook output

#!/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 = no decision; the normal permission flow applies

• Exit 0: hook Anda melaporkan tidak ada keberatan melalui kode keluarnya.
  • Untuk hook PreToolUse ini tidak menyetujui panggilan alat: alur izin normal masih berlaku.
  • Untuk hook UserPromptSubmit, UserPromptExpansion, SessionStart, dan PostModelSwitch, Claude Code menambahkan stdout yang diperlakukan sebagai teks biasa ke konteks Claude.
• Exit 2: Claude Code memblokir tindakan. Tulis alasan ke stderr. Di mana itu mendarat tergantung pada acara: beberapa acara memberinya ke Claude sebagai umpan balik sehingga dapat menyesuaikan, yang lain menampilkannya kepada pengguna, dan beberapa, seperti ConfigChange dan Elicitation, tidak menampilkan pesan. Beberapa acara tidak dapat diblokir: untuk SessionStart dan lainnya, exit 2 menampilkan stderr kepada pengguna dan eksekusi berlanjut. Lihat exit code 2 behavior per event untuk daftar lengkap.
• Kode keluar lainnya: untuk sebagian besar acara, hasilnya tergantung pada apa yang dicetak hook Anda ke stdout:
  • Objek yang diurai yang lulus validasi skema: Claude Code mengabaikan kode keluar, JSON saja yang menentukan hasilnya, dan hook tidak dilaporkan sebagai kesalahan. Pengecualian per-acara, seperti WorktreeCreate gagal pada kode keluar nonzero apa pun, tercantum di bagian Exit code output referensi.
  • Objek yang diurai yang gagal validasi skema, atau stdout yang Claude Code coba parse sebagai JSON tetapi bukan JSON yang valid: kesalahan non-blocking; pemberitahuan membawa pesan validasi atau parse.
  • Stdout yang Claude Code diperlakukan sebagai teks biasa, atau stdout kosong: tindakan berlanjut sebagai kesalahan non-blocking. Transkrip menunjukkan pemberitahuan <hook name> hook error, kemudian baris pertama stderr dengan awalan Failed with non-blocking status code:. Untuk menangkap stderr lengkap, aktifkan debug logging dengan claude --debug atau dengan menjalankan /debug di tengah sesi.

​

Structured JSON output

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

• "allow": lewati prompt izin interaktif. Aturan deny dan ask, termasuk daftar deny yang dikelola perusahaan, masih berlaku, seperti juga prompt untuk MCP tools yang ditandai requiresUserInteraction dan untuk connector tools yang organisasi Anda atur ke ask dalam sesi di mana pengaturan itu mencapai Claude Code
• "deny": batalkan panggilan alat dan kirim alasan ke Claude
• "ask": tampilkan prompt izin kepada pengguna seperti biasa

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

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"
          }
        ]
      }
    ]
  }
}

​

Filter berdasarkan nama alat dan argumen dengan bidang if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Konfigurasi lokasi hook

​

Prompt-based hooks

• "ok": true: tindakan berlanjut
• "ok": false: apa yang terjadi tergantung pada peristiwa:
  • Stop dan SubagentStop: reason diberi makan kembali ke Claude sehingga terus bekerja, kecuali respons juga menetapkan "impossible": true untuk menandai kondisi sebagai salah satu yang tidak dapat pernah dipenuhi, dalam hal ini Claude Code memungkinkan stop dan giliran berakhir
  • PreToolUse: panggilan alat ditolak; secara default giliran berakhir dan reason penolakan muncul dalam obrolan sebagai baris peringatan. Atur continueOnBlock: true pada hook untuk sebagai gantinya mengembalikan reason ke Claude sebagai kesalahan alat, sehingga dapat menyesuaikan dan melanjutkan. Sebelum v2.1.210, reason penolakan dikembalikan ke Claude sebagai kesalahan alat dan giliran berlanjut
  • PostToolUse: secara default giliran berakhir dan reason muncul dalam obrolan sebagai baris peringatan. Atur continueOnBlock: true untuk memberi makan reason kembali ke Claude dan melanjutkan giliran sebagai gantinya
  • PostToolBatch, UserPromptSubmit, dan UserPromptExpansion: giliran berakhir dan reason muncul dalam obrolan sebagai baris peringatan

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

​

Agent-based hooks

{
  "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"]
          }
        ]
      }
    ]
  }
}

​

Keterbatasan dan troubleshooting

​

Keterbatasan

• Command hooks berkomunikasi melalui stdout, stderr, dan kode keluar saja. Mereka tidak dapat memicu perintah / atau panggilan alat. Teks yang dikembalikan melalui additionalContext disuntikkan sebagai pengingat sistem yang Claude baca sebagai teks biasa. HTTP hooks berkomunikasi melalui badan respons sebagai gantinya.
• Timeout hook bervariasi menurut jenis. Timpa per hook dengan bidang timeout dalam detik.
  • command, http, mcp_tool: 10 menit. Claude Code menurunkan default ini menjadi 30 detik untuk hook UserPromptSubmit, PreModelSwitch, dan PostModelSwitch, dan menjadi 10 detik untuk hook MessageDisplay.
  • prompt: 30 detik.
  • agent: 60 detik.
  • Hook SessionEnd dari jenis apa pun berbagi anggaran 1,5 detik. Jika pengaturan Anda menetapkan timeout per-hook yang lebih lama, Claude Code menaikkan anggaran untuk cocok, hingga 60 detik.
• Hook PostToolUse tidak dapat membatalkan tindakan karena alat sudah dieksekusi.
• Hook PermissionRequest aktif ketika Claude Code akan meminta Anda untuk izin.
  • Dalam mode non-interaktif dengan flag -p, prompt itu hanya ada ketika callback canUseTool Agent SDK menyediakannya. Dalam menjalankan -p biasa atau dengan --permission-prompt-tool, gunakan hook PreToolUse untuk keputusan izin otomatis sebagai gantinya.
  • Subagen latar belakang tidak dapat menampilkan prompt dalam mode non-interaktif. Claude Code masih menjalankan hook untuk panggilan alat mereka, dan jika tidak ada hook yang mengembalikan keputusan, itu menolak panggilan. Dalam sesi interaktif, prompt subagen latar belakang muncul di sesi utama Anda dan hook aktif seperti biasa.
• Hook Stop aktif kapan pun Claude selesai merespons, bukan hanya pada penyelesaian tugas. Mereka tidak aktif pada interupsi pengguna. Kesalahan API menjalankan StopFailure sebagai gantinya.
• Ketika beberapa hook PreToolUse mengembalikan updatedInput untuk menulis ulang argumen alat, yang terakhir selesai menang. Karena hooks berjalan secara paralel, urutannya tidak deterministik. Hindari memiliki lebih dari satu hook memodifikasi input alat yang sama.

​

Hooks dan mode izin

​

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: PreToolUse aktif sebelum eksekusi alat, PostToolUse aktif setelah. Hook PermissionRequest aktif ketika Claude Code akan meminta Anda untuk izin; lihat keterbatasan untuk kasus non-interaktif

​

Hook error dalam output

• Skrip Anda keluar dengan kode non-nol secara tidak terduga. Uji secara manual dengan menyalurkan JSON sampel:
  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. Untuk menghindari quoting shell sepenuhnya, tambahkan "args": [] untuk beralih ke exec form, yang menelurkan skrip secara langsung tanpa shell
• Jika Anda melihat “jq: command not found”, instal jq atau gunakan Python/Node.js untuk parsing JSON
• Jika pemberitahuan menampilkan pesan validasi JSON, stdout hook Anda diurai sebagai JSON tetapi gagal validasi skema. Jika menampilkan pesan parsing JSON, stdout terlihat seperti objek JSON tetapi bukan JSON yang valid. Keduanya terjadi bahkan pada exit 0. Untuk memperbaiki kegagalan parsing, bangun payload dengan encoder JSON seperti jq daripada penggabungan string, sehingga tanda kutip dan garis miring terbalik di dalam nilai diloloskan. Bagian Exit code output referensi mencakup kombinasi kode keluar dan JSON
• Jika skrip tidak berjalan sama sekali, buat dapat dieksekusi: chmod +x ./my-hook.sh

​

/hooks menunjukkan tidak ada hooks yang dikonfigurasi

• Edit file biasanya diambil secara otomatis. Jika belum muncul setelah beberapa detik, file watcher mungkin melewatkan perubahan: mulai ulang sesi Anda untuk memaksa reload.
• Verifikasi JSON Anda valid: trailing commas dan comments tidak diizinkan
• Konfirmkan file pengaturan berada di lokasi yang benar: .claude/settings.json untuk hook proyek, ~/.claude/settings.json untuk hook global

​

Stop hook mencapai batas blokir

#!/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

​

Hook JSON tidak memiliki efek

• Output tambahan sebelum JSON: sesuatu yang lain menulis ke stdout terlebih dahulu, biasanya echo tanpa syarat dalam profil shell Anda, sehingga output tidak lagi dimulai dengan { dan Claude Code tidak menguraikannya sebagai JSON. Penyebab dan perbaikan mengikuti daftar ini.
• Bidang di level yang salah: bandingkan penempatan setiap bidang terhadap format JSON output. Misalnya, permissionDecision milik di dalam hookSpecificOutput, bukan di level atas.

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

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

​

Teknik debug

• Jalankan berhasil: Anda tidak melihat apa pun, kecuali JSON hook muncul sesuatu, seperti systemMessage atau umpan balik Stop hook.
  • Untuk mengonfirmasi hook berjalan, periksa efeknya, seperti file yang diformat ulang, atau aktifkan debug logging seperti dijelaskan di bawah dan picu hook lagi
• Kesalahan pemblokiran: pada sebagian besar acara Anda melihat umpan balik hook. Ketika JSON hook membuat keputusan pemblokiran, umpan balik adalah alasan dari keputusan itu; jika tidak, itu adalah stderr hook. Pada beberapa acara, seperti ConfigChange dan Elicitation, blok tidak menampilkan pesan.
• Kesalahan non-pemblokiran: tindakan dilanjutkan, dan Anda melihat pemberitahuan <hook name> hook error dengan penjelasan singkat, seperti baris pertama stderr dengan awalan Failed with non-blocking status code:, atau pesan validasi JSON atau parsing.

​

Pelajari lebih lanjut

• Hooks reference: skema acara lengkap, format output JSON, async hooks, dan MCP tool hooks
• Security considerations: tinjau sebelum menerapkan hooks dalam lingkungan bersama atau produksi
• Bash command validator example: implementasi referensi lengkap