Siapkan hook pertama Anda
Untuk membuat hook, tambahkan blokhooks ke file pengaturan. Panduan ini membuat hook notifikasi desktop, sehingga Anda mendapat peringatan kapan pun Claude menunggu input Anda daripada menonton terminal.
Tambahkan hook ke pengaturan Anda
Buka Jika file pengaturan Anda sudah memiliki kunci
~/.claude/settings.json dan tambahkan hook Notification. Contoh di bawah menggunakan osascript untuk macOS; lihat Dapatkan notifikasi ketika Claude memerlukan input untuk perintah Linux dan Windows.hooks, gabungkan entri Notification ke dalamnya daripada mengganti seluruh objek. Anda juga dapat meminta Claude untuk menulis hook untuk Anda dengan mendeskripsikan apa yang Anda inginkan di CLI.Verifikasi konfigurasi
Ketik
/hooks untuk membuka browser hooks. Anda akan melihat daftar semua acara hook yang tersedia, dengan hitungan di sebelah setiap acara yang memiliki hooks yang dikonfigurasi. Pilih Notification untuk mengonfirmasi hook baru Anda muncul dalam daftar. Memilih hook menampilkan detailnya: acara, matcher, jenis, file sumber, dan perintah.Apa yang dapat Anda otomatisasi
Hooks memungkinkan Anda menjalankan kode pada titik-titik kunci dalam siklus hidup Claude Code: format file setelah edit, blokir perintah sebelum dijalankan, kirim notifikasi ketika Claude memerlukan input, injeksi konteks saat awal sesi, dan banyak lagi. Untuk daftar lengkap acara hook, lihat Hooks reference. Setiap contoh mencakup blok konfigurasi siap pakai yang Anda tambahkan ke file pengaturan. Pola paling umum:- Dapatkan notifikasi ketika Claude memerlukan input
- Auto-format kode setelah edit
- Blokir edit ke file yang dilindungi
- Re-inject konteks setelah compaction
- Audit perubahan konfigurasi
- Muat ulang lingkungan ketika direktori atau file berubah
- Auto-approve prompt izin tertentu
Dapatkan notifikasi ketika Claude memerlukan input
Dapatkan notifikasi desktop kapan pun Claude selesai bekerja dan memerlukan input Anda, sehingga Anda dapat beralih ke tugas lain tanpa memeriksa terminal. Hook ini menggunakan acaraNotification, yang aktif ketika Claude menunggu input atau izin. Setiap tab di bawah menggunakan perintah notifikasi asli platform. Tambahkan ini ke ~/.claude/settings.json:
- macOS
- Linux
- Windows (PowerShell)
Auto-format kode setelah edit
Jalankan Prettier secara otomatis pada setiap file yang Claude edit, sehingga pemformatan tetap konsisten tanpa intervensi manual. Hook ini menggunakan acaraPostToolUse dengan matcher Edit|Write, sehingga hanya berjalan setelah alat pengeditan file. Perintah mengekstrak jalur file yang diedit dengan jq dan meneruskannya ke Prettier. Tambahkan ini ke .claude/settings.json di root proyek Anda:
Contoh Bash di halaman ini menggunakan
jq untuk parsing JSON. Instal dengan brew install jq (macOS), apt-get install jq (Debian/Ubuntu), atau lihat jq downloads.Blokir edit ke file yang dilindungi
Cegah Claude dari memodifikasi file sensitif seperti.env, package-lock.json, atau apa pun di .git/. Claude menerima umpan balik yang menjelaskan mengapa edit diblokir, sehingga dapat menyesuaikan pendekatannya.
Contoh ini menggunakan file skrip terpisah yang dipanggil hook. Skrip memeriksa jalur file target terhadap daftar pola yang dilindungi dan keluar dengan kode 2 untuk memblokir edit.
Buat skrip dapat dieksekusi (macOS/Linux)
Skrip hook harus dapat dieksekusi agar Claude Code dapat menjalankannya:
Re-inject konteks setelah compaction
Ketika jendela konteks Claude penuh, compaction merangkum percakapan untuk membebaskan ruang. Ini dapat kehilangan detail penting. Gunakan hookSessionStart dengan matcher compact untuk re-inject konteks kritis setelah setiap compaction.
Teks apa pun yang ditulis perintah Anda ke stdout ditambahkan ke konteks Claude. Contoh ini mengingatkan Claude tentang konvensi proyek dan pekerjaan terbaru. Tambahkan ini ke .claude/settings.json di root proyek Anda:
echo dengan perintah apa pun yang menghasilkan output dinamis, seperti git log --oneline -5 untuk menampilkan commit terbaru. Untuk injeksi konteks pada setiap awal sesi, pertimbangkan menggunakan CLAUDE.md sebagai gantinya. Untuk variabel lingkungan, lihat CLAUDE_ENV_FILE dalam referensi.
Audit perubahan konfigurasi
Lacak ketika file pengaturan atau skills berubah selama sesi. AcaraConfigChange aktif ketika proses eksternal atau editor memodifikasi file konfigurasi, sehingga Anda dapat mencatat perubahan untuk kepatuhan atau memblokir modifikasi yang tidak sah.
Contoh ini menambahkan setiap perubahan ke log audit. Tambahkan ini ke ~/.claude/settings.json:
user_settings, project_settings, local_settings, policy_settings, atau skills. Untuk memblokir perubahan agar tidak berlaku, keluar dengan kode 2 atau kembalikan {"decision": "block"}. Lihat ConfigChange reference untuk skema input lengkap.
Muat ulang lingkungan ketika direktori atau file berubah
Beberapa proyek menetapkan variabel lingkungan berbeda tergantung pada direktori mana Anda berada. Alat seperti direnv melakukan ini secara otomatis di shell Anda, tetapi alat Bash Claude tidak mengambil perubahan itu sendiri. HookCwdChanged memperbaiki ini: ia berjalan setiap kali Claude mengubah direktori, sehingga Anda dapat memuat ulang variabel yang benar untuk lokasi baru. Hook menulis nilai yang diperbarui ke CLAUDE_ENV_FILE, yang Claude Code terapkan sebelum setiap perintah Bash. Tambahkan ini ke ~/.claude/settings.json:
FileChanged dengan matcher yang mencantumkan nama file yang akan dipantau (dipisahkan dengan pipa). matcher mengonfigurasi file mana yang akan dipantau dan memfilter hook mana yang berjalan. Contoh ini memantau .envrc dan .env untuk perubahan di direktori saat ini:
watchPaths, dan detail CLAUDE_ENV_FILE.
Auto-approve prompt izin tertentu
Lewati dialog persetujuan untuk panggilan alat yang selalu Anda izinkan. Contoh ini auto-approveExitPlanMode, alat yang Claude panggil ketika selesai menyajikan rencana dan meminta untuk melanjutkan, sehingga Anda tidak diminta setiap kali rencana siap.
Tidak seperti contoh kode keluar di atas, auto-approval memerlukan hook Anda untuk menulis keputusan JSON ke stdout. Hook PermissionRequest aktif ketika Claude Code akan menampilkan dialog izin, dan mengembalikan "behavior": "allow" menjawabnya atas nama Anda.
Matcher membatasi hook ke ExitPlanMode saja, sehingga tidak ada prompt lain yang terpengaruh. Tambahkan ini ke ~/.claude/settings.json:
updatedPermissions dengan entri setMode. Nilai mode adalah mode izin apa pun seperti default, acceptEdits, atau bypassPermissions, dan destination: "session" menerapkannya hanya untuk sesi saat ini.
Untuk beralih sesi ke acceptEdits, hook Anda menulis JSON ini ke stdout:
.* atau membiarkan matcher kosong akan auto-approve setiap prompt izin, termasuk penulisan file dan perintah shell. Lihat PermissionRequest reference untuk set lengkap bidang keputusan.
Cara kerja hooks
Acara hook aktif pada titik-titik siklus hidup spesifik di Claude Code. Ketika acara aktif, semua hook yang cocok berjalan secara paralel, dan perintah hook yang identik secara otomatis dideduplikasi. Tabel di bawah menunjukkan setiap acara dan kapan dipicu:| Event | When it fires |
|---|---|
SessionStart | When a session begins or resumes |
UserPromptSubmit | When you submit a prompt, before Claude processes it |
PreToolUse | Before a tool call executes. Can block it |
PermissionRequest | When a permission dialog appears |
PermissionDenied | When a tool call is denied by the auto mode classifier. Return {retry: true} to tell the model it may retry the denied tool call |
PostToolUse | After a tool call succeeds |
PostToolUseFailure | After a tool call fails |
Notification | When Claude Code sends a notification |
SubagentStart | When a subagent is spawned |
SubagentStop | When a subagent finishes |
TaskCreated | When a task is being created via TaskCreate |
TaskCompleted | When a task is being marked as completed |
Stop | When Claude finishes responding |
StopFailure | When the turn ends due to an API error. Output and exit code are ignored |
TeammateIdle | When an agent team teammate is about to go idle |
InstructionsLoaded | When a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a session |
ConfigChange | When a configuration file changes during a session |
CwdChanged | When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv |
FileChanged | When a watched file changes on disk. The matcher field specifies which filenames to watch |
WorktreeCreate | When a worktree is being created via --worktree or isolation: "worktree". Replaces default git behavior |
WorktreeRemove | When a worktree is being removed, either at session exit or when a subagent finishes |
PreCompact | Before context compaction |
PostCompact | After context compaction completes |
Elicitation | When an MCP server requests user input during a tool call |
ElicitationResult | After a user responds to an MCP elicitation, before the response is sent back to the server |
SessionEnd | When a session terminates |
type yang menentukan cara menjalankannya. Sebagian besar hooks menggunakan "type": "command", yang menjalankan perintah shell. Tiga jenis lain tersedia:
"type": "http": POST data acara ke URL. Lihat HTTP hooks."type": "prompt": evaluasi LLM single-turn. Lihat Prompt-based hooks."type": "agent": verifikasi multi-turn dengan akses alat. Lihat Agent-based hooks.
Baca input dan kembalikan output
Hooks berkomunikasi dengan Claude Code melalui stdin, stdout, stderr, dan kode keluar. Ketika acara aktif, Claude Code meneruskan data spesifik acara sebagai JSON ke stdin skrip Anda. Skrip Anda membaca data itu, melakukan pekerjaan, dan memberi tahu Claude Code apa yang harus dilakukan selanjutnya melalui kode keluar.Hook input
Setiap acara mencakup bidang umum sepertisession_id dan cwd, tetapi setiap jenis acara menambahkan data berbeda. Misalnya, ketika Claude menjalankan perintah Bash, hook PreToolUse menerima sesuatu seperti ini di stdin:
UserPromptSubmit mendapatkan teks prompt sebagai gantinya, hook SessionStart mendapatkan source (startup, resume, clear, compact), dan seterusnya. Lihat Common input fields dalam referensi untuk bidang bersama, dan bagian setiap acara untuk skema spesifik acara.
Hook output
Skrip Anda memberi tahu Claude Code apa yang harus dilakukan selanjutnya dengan menulis ke stdout atau stderr dan keluar dengan kode spesifik. Misalnya, hookPreToolUse yang ingin memblokir perintah:
- Exit 0: tindakan berlanjut. Untuk hook
UserPromptSubmitdanSessionStart, 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+Ountuk melihat pesan ini dalam transkrip.
Structured JSON output
Kode keluar memberi Anda dua opsi: izinkan atau blokir. Untuk kontrol lebih, keluar 0 dan cetak objek JSON ke stdout sebagai gantinya.Gunakan exit 2 untuk memblokir dengan pesan stderr, atau exit 0 dengan JSON untuk kontrol terstruktur. Jangan campur: Claude Code mengabaikan JSON ketika Anda exit 2.
PreToolUse dapat menolak panggilan alat dan memberi tahu Claude mengapa, atau meningkatkannya ke pengguna untuk persetujuan:
permissionDecision dan membatalkan panggilan alat, kemudian memberi makan permissionDecisionReason kembali ke Claude sebagai umpan balik. Tiga opsi ini spesifik untuk PreToolUse:
"allow": lanjutkan tanpa menampilkan prompt izin interaktif. Aturan deny dan ask, termasuk daftar deny yang dikelola perusahaan, masih berlaku"deny": batalkan panggilan alat dan kirim alasan ke Claude"ask": tampilkan prompt izin kepada pengguna seperti biasa
"allow" melewati prompt interaktif tetapi tidak mengesampingkan aturan izin. Jika aturan deny cocok dengan panggilan alat, panggilan diblokir bahkan ketika hook Anda mengembalikan "allow". Jika aturan ask cocok, pengguna masih diminta. Ini berarti aturan deny dari cakupan pengaturan apa pun, termasuk pengaturan terkelola, selalu mengambil alih persetujuan hook.
Acara lain menggunakan pola keputusan berbeda. Misalnya, hook PostToolUse dan Stop menggunakan bidang decision: "block" tingkat atas, sementara PermissionRequest menggunakan hookSpecificOutput.decision.behavior. Lihat summary table dalam referensi untuk rincian lengkap berdasarkan acara.
Untuk hook UserPromptSubmit, gunakan additionalContext sebagai gantinya untuk menyuntikkan teks ke dalam konteks Claude. Hook berbasis prompt (type: "prompt") menangani output secara berbeda: lihat Prompt-based hooks.
Filter hooks dengan matchers
Tanpa matcher, hook aktif pada setiap kemunculan acaranya. Matchers memungkinkan Anda mempersempit itu. Misalnya, jika Anda ingin menjalankan formatter hanya setelah edit file (bukan setelah setiap panggilan alat), tambahkan matcher ke hookPostToolUse Anda:
"Edit|Write" adalah pola regex yang cocok dengan nama alat. Hook hanya aktif ketika Claude menggunakan alat Edit atau Write, bukan ketika menggunakan Bash, Read, atau alat lainnya.
Setiap jenis acara cocok pada bidang spesifik. Matchers mendukung string tepat dan pola regex:
| Acara | Apa yang difilter matcher | Contoh nilai matcher |
|---|---|---|
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest | nama alat | Bash, Edit|Write, mcp__.* |
SessionStart | cara sesi dimulai | startup, resume, clear, compact |
SessionEnd | mengapa sesi berakhir | clear, resume, logout, prompt_input_exit, bypass_permissions_disabled, other |
Notification | jenis notifikasi | permission_prompt, idle_prompt, auth_success, elicitation_dialog |
SubagentStart | jenis agen | Bash, Explore, Plan, atau nama agen khusus |
PreCompact, PostCompact | apa yang memicu compaction | manual, auto |
SubagentStop | jenis agen | nilai yang sama seperti SubagentStart |
ConfigChange | sumber konfigurasi | user_settings, project_settings, local_settings, policy_settings, skills |
StopFailure | jenis kesalahan | rate_limit, authentication_failed, billing_error, invalid_request, server_error, max_output_tokens, unknown |
InstructionsLoaded | alasan pemuatan | session_start, nested_traversal, path_glob_match, include, compact |
Elicitation | nama server MCP | nama server MCP yang dikonfigurasi Anda |
ElicitationResult | nama server MCP | nilai yang sama seperti Elicitation |
FileChanged | nama file (basename file yang berubah) | .envrc, .env, nama file apa pun yang ingin Anda pantau |
UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged | tidak ada dukungan matcher | selalu aktif pada setiap kemunculan |
- Catat setiap perintah Bash
- Cocokkan alat MCP
- Bersihkan saat akhir sesi
Cocokkan hanya panggilan alat
Bash dan catat setiap perintah ke file. Acara PostToolUse aktif setelah perintah selesai, jadi tool_input.command berisi apa yang berjalan. Hook menerima data acara sebagai JSON di stdin, dan jq -r '.tool_input.command' mengekstrak hanya string perintah, yang >> tambahkan ke file log:Konfigurasi lokasi hook
Di mana Anda menambahkan hook menentukan cakupannya:| Lokasi | Cakupan | Dapat Dibagikan |
|---|---|---|
~/.claude/settings.json | Semua proyek Anda | Tidak, lokal ke mesin Anda |
.claude/settings.json | Proyek tunggal | Ya, dapat dikomit ke repo |
.claude/settings.local.json | Proyek tunggal | Tidak, gitignored |
| Pengaturan kebijakan terkelola | Seluruh organisasi | Ya, dikendalikan admin |
Plugin hooks/hooks.json | Ketika plugin diaktifkan | Ya, dikemas dengan plugin |
| Skill atau agent frontmatter | Saat skill atau agent aktif | Ya, didefinisikan dalam file komponen |
/hooks di Claude Code untuk menjelajahi semua hooks yang dikonfigurasi dikelompokkan berdasarkan acara. Untuk menonaktifkan semua hooks sekaligus, atur "disableAllHooks": true dalam file pengaturan Anda.
Jika Anda mengedit file pengaturan secara langsung saat Claude Code berjalan, file watcher biasanya mengambil perubahan hook secara otomatis.
Prompt-based hooks
Untuk keputusan yang memerlukan penilaian daripada aturan deterministik, gunakan hooktype: "prompt". Daripada menjalankan perintah shell, Claude Code mengirim prompt Anda dan data input hook ke model Claude (Haiku secara default) untuk membuat keputusan. Anda dapat menentukan model berbeda dengan bidang model jika Anda memerlukan kemampuan lebih.
Satu-satunya pekerjaan model adalah mengembalikan keputusan ya/tidak sebagai JSON:
"ok": true: tindakan berlanjut"ok": false: tindakan diblokir."reason"model diberi makan kembali ke Claude sehingga dapat menyesuaikan.
Stop untuk menanyakan kepada model apakah semua tugas yang diminta selesai. Jika model mengembalikan "ok": false, Claude terus bekerja dan menggunakan reason sebagai instruksi berikutnya:
Agent-based hooks
Ketika verifikasi memerlukan inspeksi file atau menjalankan perintah, gunakan hooktype: "agent". Tidak seperti hook prompt yang membuat panggilan LLM tunggal, hook agent menelurkan subagent yang dapat membaca file, mencari kode, dan menggunakan alat lain untuk memverifikasi kondisi sebelum mengembalikan keputusan.
Hook agent menggunakan format respons "ok" / "reason" yang sama seperti hook prompt, tetapi dengan timeout default lebih lama 60 detik dan hingga 50 putaran penggunaan alat.
Contoh ini memverifikasi bahwa tes lulus sebelum memungkinkan Claude berhenti:
HTTP hooks
Gunakan hooktype: "http" untuk POST data acara ke endpoint HTTP daripada menjalankan perintah shell. Endpoint menerima JSON yang sama yang diterima hook perintah di stdin, dan mengembalikan hasil melalui badan respons HTTP menggunakan format JSON yang sama.
HTTP hooks berguna ketika Anda ingin server web, fungsi cloud, atau layanan eksternal menangani logika hook: misalnya, layanan audit bersama yang mencatat acara penggunaan alat di seluruh tim.
Contoh ini memposting setiap penggunaan alat ke layanan logging lokal:
hookSpecificOutput yang sesuai. Kode status HTTP saja tidak dapat memblokir tindakan.
Nilai header mendukung interpolasi variabel lingkungan menggunakan sintaks $VAR_NAME atau ${VAR_NAME}. Hanya variabel yang tercantum dalam array allowedEnvVars yang diselesaikan; semua referensi $VAR lainnya tetap kosong.
Untuk opsi konfigurasi lengkap dan penanganan respons, lihat HTTP hooks dalam referensi.
Keterbatasan dan troubleshooting
Keterbatasan
- Hook 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
PostToolUsetidak dapat membatalkan tindakan karena alat sudah dieksekusi. - Hook
PermissionRequesttidak aktif dalam non-interactive mode (-p). Gunakan hookPreToolUseuntuk keputusan izin otomatis. - Hook
Stopaktif kapan pun Claude selesai merespons, bukan hanya pada penyelesaian tugas. Mereka tidak aktif pada interupsi pengguna. Kesalahan API menjalankan StopFailure sebagai gantinya.
Hook tidak aktif
Hook dikonfigurasi tetapi tidak pernah dieksekusi.- Jalankan
/hooksdan konfirmasi hook muncul di bawah acara yang benar - Periksa bahwa pola matcher cocok dengan nama alat dengan tepat (matcher peka huruf besar-kecil)
- Verifikasi Anda memicu jenis acara yang benar (misalnya,
PreToolUseaktif sebelum eksekusi alat,PostToolUseaktif setelah) - Jika menggunakan hook
PermissionRequestdalam mode non-interaktif (-p), beralih kePreToolUsesebagai gantinya
Hook error dalam output
Anda melihat pesan seperti “PreToolUse hook error: …” dalam transkrip.- Skrip Anda keluar dengan kode non-nol secara tidak terduga. Uji secara manual dengan menyalurkan JSON sampel:
- Jika Anda melihat “command not found”, gunakan jalur absolut atau
$CLAUDE_PROJECT_DIRuntuk mereferensikan skrip - Jika Anda melihat “jq: command not found”, instal
jqatau gunakan Python/Node.js untuk parsing JSON - Jika skrip tidak berjalan sama sekali, buat dapat dieksekusi:
chmod +x ./my-hook.sh
/hooks menunjukkan tidak ada hooks yang dikonfigurasi
Anda mengedit file pengaturan tetapi hooks tidak muncul dalam menu.
- 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.jsonuntuk hook proyek,~/.claude/settings.jsonuntuk hook global
Stop hook berjalan selamanya
Claude terus bekerja dalam loop tak terbatas daripada berhenti. Skrip Stop hook Anda perlu memeriksa apakah sudah memicu kelanjutan. Parsing bidangstop_hook_active dari input JSON dan keluar lebih awal jika true:
JSON validation failed
Claude Code menampilkan kesalahan parsing JSON meskipun skrip hook Anda mengeluarkan JSON yang valid. Ketika Claude Code menjalankan hook, ia menelurkan shell yang bersumber dari profil Anda (~/.zshrc atau ~/.bashrc). Jika profil Anda berisi pernyataan echo tanpa syarat, output itu ditambahkan ke JSON hook Anda:
$- berisi flag shell, dan i berarti interaktif. Hooks berjalan di shell non-interaktif, jadi echo dilewati.
Teknik debug
Alihkan mode verbose denganCtrl+O untuk melihat output hook dalam transkrip, atau jalankan claude --debug untuk detail eksekusi lengkap termasuk hook mana yang cocok dan kode keluar mereka.
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