Hook Claude Code tidak berfungsi di Windows: penyebab dan solusinya

Hook yang sama yang berjalan lancar di Mac tidak melakukan apa-apa di Windows, atau lebih parah lagi, memblokir setiap perintah. Hampir selalu penyebabnya adalah shell. Berikut cara Claude Code menjalankan hook di Windows dan cara membuat hook Anda andal.

Oleh Aslan, tim Pet Island · Diperbarui 26 Okt 2026 · 5 menit baca

JAWABAN SINGKAT

Di Windows, Claude Code menjalankan command milik hook dengan Git Bash, atau dengan PowerShell jika Git Bash tidak terpasang. Tentukan mana yang Anda maksud dengan "shell": "powershell" atau "shell": "bash", pastikan stdout hanya berisi satu objek JSON (tanpa echo dari profil), gunakan kode keluar 2 untuk memblokir, dan perbarui Claude Code (beberapa bug hook di Windows diperbaiki dalam versi hingga 2.1.310). Lakukan debug dengan /hooks dan claude --debug.

Shell mana yang menjalankan hook Anda

Claude Code meneruskan string command ke sebuah shell: sh -c di macOS dan Linux, Git Bash di Windows, atau PowerShell jika Git Bash tidak terpasang. Satu kalimat dari referensi hook itu menjelaskan sebagian besar laporan “di Mac saya berfungsi”. Perintah yang ditulis untuk PowerShell gagal di Git Bash, skrip bash gagal di PowerShell, dan mana yang Anda dapatkan bergantung pada apakah Git for Windows kebetulan terpasang.

Hilangkan tebak-tebakan dengan kolom shell. Kolom ini menerima "bash" atau "powershell":

%USERPROFILE%\.claude\settings.jsonSalin

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [

{

"type": "command",

"shell": "powershell",

"command": "[Console]::Beep(880, 200)"

}

]

}

]

}

Jika Anda ingin memakai Git Bash tetapi Claude Code tidak dapat menemukannya, pasang Git for Windows atau setel CLAUDE_CODE_GIT_BASH_PATH ke lokasinya, lalu mulai sesi baru.

Gejala dan penyebabnya

Yang Anda lihat	Kemungkinan penyebab	Solusi
Hook sepertinya tidak pernah berjalan	Versi Claude Code lama, event atau matcher yang salah, JSON tidak valid di pengaturan	Perbarui; cek `/hooks`; hapus komentar dan koma di akhir
`ParserError` atau “unexpected token”	Sintaks PowerShell sampai ke Git Bash, atau sebaliknya	Setel `shell` secara eksplisit
Output hook “does not start with {”	Ada sesuatu yang dicetak sebelum JSON, sering kali dari profil shell	Bungkam output profil; kirim log ke stderr
Path dengan campuran `\` dan `/` tidak dapat ditemukan	Variabel path Windows digabung dengan akhiran bergaya Unix	Gunakan bentuk exec: program di `command`, setiap argumen di `args`
`powershell: Permission denied` dari Git Bash	Dilaporkan sesekali terjadi di 2.1.283 dan 2.1.304–2.1.305 (#103910, masih terbuka)	Gunakan `"shell": "powershell"` agar Git Bash tidak menjadi perantara
Hook penjaga meloloskan semuanya	Kode keluar 1, bukan 2, atau bug fail-open di versi lama	Keluar dengan 2 untuk memblokir; perbarui ke 2.1.310 atau yang lebih baru
Hook langsung selesai tanpa output	Program subsistem GUI yang tidak ditunggu oleh shell	Gunakan program konsol, atau tunggu prosesnya

Hanya JSON di stdout

Claude Code membaca output standar hook Anda sebagai jawabannya. Aturan di dokumentasinya singkat: jangan mencetak apa pun ke stdout selain objek JSON. Di Windows, aturan ini bisa dilanggar dengan cara yang sulit dikenali: Git Bash dan beberapa konfigurasi tetap memuat profil shell Anda, dan echo tanpa syarat di profil itu ditambahkan di depan JSON Anda. Akibatnya, hook “berfungsi” di terminal tetapi gagal di dalam Claude Code.

Sebagai gantinya, tulis log ke file atau ke stderr, dan buat output profil Anda hanya muncul di shell interaktif.

Kode keluar: 2 memblokir, 1 tidak

Keluar dengan 0 berarti sukses. Keluar dengan 2 adalah error yang memblokir: pada event yang dapat diblokir, Claude Code menghentikan tindakan dan menampilkan stderr Anda. Keluar dengan 1 tanpa JSON yang valid adalah error yang tidak memblokir, dan tindakan tetap berjalan. Jika hook Anda menegakkan kebijakan, gunakan exit 2.

Tidak semua event bisa diblokir dengan cara ini. Kode keluar hook Notification diabaikan. Hook Stop yang keluar dengan 2 membuat Claude terus bekerja. Hook PermissionRequest sepenuhnya mengabaikan exit 2. Hook ini memutuskan melalui objek decision di JSON-nya.

Claude Code 2.1.309 memperbaiki hook PowerShell yang tidak memblokir saat program hook keluar dengan kode 2. Jika hook penjaga PowerShell Anda tampak diabaikan, cek versi Anda terlebih dahulu.

Perbaikan Windows yang membuat pembaruan layak dilakukan

Changelog Anthropic memuat deretan panjang perbaikan hook di Windows. Berikut yang menjelaskan thread forum lama:

Versi	Perbaikan
2.1.47	Hook PreToolUse dan PostToolUse gagal tanpa pesan di Windows; kini hook tersebut berjalan dengan Git Bash, bukan cmd.exe
2.1.161	Hook yang memanggil bash secara eksplisit (`/usr/bin/bash script.sh`) gagal dengan “command not found”
2.1.299	Hook PreToolUse dan PermissionRequest tanpa shell yang disetel gagal secara fail-open tanpa Git for Windows; kini hook penjaga yang gagal akan memblokir
2.1.309	Hook PowerShell tidak memblokir pada kode keluar 2; hook penjaga dengan `"shell": "powershell"` gagal secara fail-open tanpa Git for Windows
2.1.310	Hook penjaga yang perintahnya hanya berupa string berkutip (seperti path berkutip) gagal secara fail-open tanpa Git Bash

Issue lama berjudul “No hook is working on Windows” (#10450) dilaporkan pada 2.0.27; seorang pemberi komentar menemukan penyebabnya: stdin tidak sampai ke perintah hook. Jika Anda masih memakai versi setua itu, perbarui sebelum men-debug hal lain.

Memanggil program secara langsung

Jika hook Anda berupa program yang dikompilasi, Anda bisa melewati shell dengan bentuk exec (kolom args; shell diabaikan saat args disetel). Di Windows, bentuk exec mengharuskan command mengarah ke file executable sungguhan seperti .exe; shim .cmd dan .bat (termasuk sebagian besar yang dipasang npm) tidak bisa dijalankan tanpa shell. Arahkan ke .exe, atau gunakan bentuk shell.

Satu pelajaran dari membangun helper hook kami sendiri: di Windows, program yang dibangun untuk subsistem GUI tidak ditunggu saat dijalankan oleh shell. Shell langsung selesai, agen membaca output kosong, dan hook tampak mati. Program hook harus berupa program konsol.

Hook plugin dan path

Hook plugin yang membangun path seperti ${CLAUDE_PLUGIN_ROOT}/hooks/run.sh rusak di Windows antara v2.1.2 dan v2.1.12 (#18610): variabelnya diekspansi menjadi path dengan backslash, dan menambahkan akhiran dengan garis miring biasa menghasilkan path campuran yang tidak bisa diselesaikan bash. Dokumentasi terbaru memberikan solusi yang bersih: gunakan bentuk exec setiap kali hook merujuk placeholder path. Letakkan program di command dan setiap argumen di args, misalnya "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js"]. Setiap elemen diteruskan sebagai satu argumen, tanpa shell yang bisa merusaknya.

Daftar periksa debugging

/hooks membuka daftar read-only berisi setiap hook yang dikonfigurasi beserta asalnya.
claude --debug (atau /debug di tengah sesi) menampilkan setiap eksekusi hook, output-nya, dan kode keluarnya. claude --debug-file <path> menuliskannya ke file.
Validasi JSON-nya. File pengaturan adalah JSON ketat; satu koma di akhir menonaktifkan seluruh file.
Cek matcher-nya. Matcher peka huruf besar-kecil; "*", "", atau tanpa matcher akan mencocokkan semuanya.
Jalankan perintahnya sendiri di shell yang sama yang akan dipakai Claude Code, dengan contoh JSON yang di-pipe sebagai input.
Perhatikan timeout-nya. Hook perintah secara default memiliki timeout 600 detik; hook yang menunggu respons seseorang membutuhkan ruang waktu itu.

Untuk menonaktifkan semua hook selama Anda menyelidiki, setel "disableAllHooks": true.

Jika Anda hanya menginginkan notifikasi dan persetujuan

Banyak konfigurasi hook di Windows dibuat untuk satu alasan: mengetahui kapan Claude Code membutuhkan Anda dan menjawabnya. Pet Island melakukannya tanpa skrip apa pun. Pet Island terhubung ke Claude Code dengan sekali klik, menangani detail Windows untuk Anda, dan menempatkan setiap permintaan izin, pertanyaan, dan rencana di sebuah island kecil di bagian atas layar, beserta perintah atau diff-nya, tempat Anda mengizinkan atau menolaknya. Pet Island juga berfungsi saat Claude Code berjalan di dalam WSL.

FAQ

Shell mana yang menjalankan hook Claude Code di Windows?

Git Bash, atau PowerShell jika Git Bash tidak terpasang. Setel "shell": "powershell" atau "shell": "bash" di hook untuk memilih secara eksplisit.

Mengapa hook Claude Code saya berfungsi di terminal tetapi tidak di Claude Code?

Biasanya karena output tambahan: profil shell yang mencetak teks ditambahkan di depan JSON hook. Cetak hanya objek JSON ke stdout.

Bagaimana cara membuat hook memblokir pemanggilan alat?

Keluar dengan kode 2 (atau kembalikan keputusan deny dalam JSON). Kode keluar 1 adalah error yang tidak memblokir, dan tindakan tetap berjalan. Hook PermissionRequest mengabaikan exit 2 dan memakai objek decision sebagai gantinya.

Bisakah perintah hook berupa file .cmd atau .bat?

Tidak dalam bentuk exec. Di Windows, perintah harus mengarah ke file executable sungguhan seperti .exe. Gunakan bentuk shell untuk menjalankan file .cmd atau .bat.

Bagaimana cara melihat mengapa hook gagal?

Jalankan claude --debug atau ketik /debug, dan gunakan /hooks untuk melihat hook mana yang dimuat.

Sumber

Setiap pengaturan dan perilaku di halaman ini telah dicocokkan dengan halaman-halaman berikut pada 26 Oktober 2026. Agen berubah dengan cepat; jika ada yang tidak lagi sesuai, halaman resmi yang berlaku.