Ringkasan Singkat: Hook Claude Code adalah skrip otomatisasi yang dieksekusi pada titik siklus hidup tertentu selama sesi pengkodean AI, memungkinkan pengembang untuk menjalankan perintah kustom, memvalidasi tindakan, memformat kode, mengirim notifikasi, dan menegakkan aturan proyek. Hook ini terintegrasi dengan alur kerja Claude melalui peristiwa seperti SessionStart, PreToolUse, dan PostToolUse, mendukung pola eksekusi berbasis perintah, berbasis HTTP, dan berbasis prompt dengan batas waktu yang dapat dikonfigurasi dan perilaku kode keluar.
Sistem hook Claude Code mengubah asisten pengkodean AI dari alat bantu menjadi lingkungan pengembangan yang sepenuhnya otomatis. Sebagian besar pengembang tidak menyadari sejauh mana kontrol yang tersedia melalui hook.
Begini masalahnya—hook bukan hanya tentang menjalankan skrip setelah pengeditan file. Hook menyediakan titik intersepsi di seluruh proses pengambilan keputusan Claude. Sebelum mengeksekusi perintah. Setelah panggilan alat gagal. Saat memerlukan izin. Bahkan sebelum memproses prompt pengguna.
Panduan ini mencakup semua yang disediakan dokumentasi resmi, ditambah pola praktis yang terungkap dalam diskusi komunitas yang benar-benar berfungsi di lingkungan produksi.
Apa yang Sebenarnya Dilakukan Hook Claude Code
Menurut dokumentasi resmi Claude Code, hook adalah perintah shell yang ditentukan pengguna, titik akhir HTTP, atau injeksi prompt yang dieksekusi pada titik-titik tertentu dalam siklus hidup Claude Code. Hook menerima input JSON terstruktur melalui stdin dan mengontrol alur kerja melalui kode keluar atau respons HTTP.
Otomatisasi berjalan lebih dalam daripada yang disarankan sebagian besar panduan. Hook dapat sepenuhnya memblokir eksekusi alat, menyuntikkan konteks tambahan ke dalam penalaran Claude, memicu layanan eksternal, dan menegakkan aturan validasi yang harus dipatuhi Claude.
Ada tiga jenis hook inti:
- Hook perintah: Skrip shell yang berkomunikasi melalui stdout, stderr, dan kode keluar
- Hook HTTP: Titik akhir jarak jauh yang menerima permintaan POST dan mengembalikan respons JSON
- Hook prompt: Instruksi dinamis yang disuntikkan ke dalam konteks Claude pada peristiwa tertentu
Setiap jenis melayani pola otomatisasi yang berbeda. Hook perintah menangani validasi dan pemformatan lokal. Hook HTTP terintegrasi dengan layanan eksternal dan database. Hook prompt memodifikasi perilaku Claude tanpa proses eksternal.
Siklus Hidup Hook dan Sistem Peristiwa
Dokumentasi resmi mendefinisikan beberapa peristiwa hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, dan lainnya) yang aktif selama alur eksekusi Claude Code. Memahami kapan setiap peristiwa aktif menentukan otomatisasi apa yang mungkin dilakukan.
| Peristiwa | Kapan Aktif | Dapat Memblokir |
|---|---|---|
| SessionStart | Saat sesi dimulai atau dilanjutkan | Tidak |
| UserPromptSubmit | Saat Anda mengirimkan prompt, sebelum Claude memprosesnya | Ya |
| PreToolUse | Sebelum alat dieksekusi | Ya |
| PermissionRequest | Saat dialog izin muncul | Ya |
| PostToolUse | Setelah alat berhasil dieksekusi | Tidak |
| PostToolUseFailure | Setelah alat gagal dieksekusi | Tidak |
| Notification | Saat Claude Code mengirimkan notifikasi | Tidak |
| SubmitMessage | Saat Claude mengirimkan pesan ke pengguna | Tidak |
| ContextCompaction | Saat jendela konteks mendekati batas | Tidak |
Kemampuan pemblokiran adalah yang paling penting. Hook PreToolUse dapat mencegah operasi berbahaya sebelum dieksekusi. Kode keluar 1 memblokir tindakan. Kode keluar 0 mengizinkannya. Kode keluar 2 membuat Claude mempertimbangkan kembali.
Namun tunggu dulu. Hook PostToolUse tidak dapat membatalkan tindakan karena alat sudah dieksekusi. Keterbatasan ini membentuk cara logika validasi disusun. Pemeriksaan kritis ada di PreToolUse. Pembersihan dan pemformatan ada di PostToolUse.
Jelajahi Keuntungan Alat AI Saat Menyiapkan Claude Code
Jika Anda bekerja dengan hook Claude Code, Anda mungkin juga memilih alat AI lain di sekitar alur kerja Anda. Get AI Perks mengumpulkan kredit startup dan diskon perangkat lunak untuk alat AI dan cloud di satu tempat. Platform ini mencakup lebih dari 200 penawaran, dengan kondisi keuntungan dan panduan klaim untuk masing-masing penawaran.
Mencari Keuntungan Claude atau Alat AI Lainnya?
Periksa Get AI Perks untuk:
- menjelajahi penawaran Claude dan alat AI lainnya
- membandingkan kondisi keuntungan sebelum mengajukan
- menemukan diskon startup di seluruh tumpukan alat Anda
👉 Kunjungi Get AI Perks untuk menjelajahi keuntungan perangkat lunak AI saat ini.
Struktur Konfigurasi dan File
Hook ditentukan dalam file .claude/settings.json di dalam proyek. Skema konfigurasi mendukung hook global dan pencocok khusus alat yang memfilter kapan hook dieksekusi.
Struktur hook perintah dasar:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Variabel ${file} diperluas ke jalur file aktual dari input alat. Menurut dokumentasi resmi, hook mendukung ekspansi variabel ini di bidang perintah dan argumen.
Hierarki Lokasi Hook
Claude Code memeriksa beberapa lokasi untuk definisi hook, dengan urutan prioritas yang jelas:
- Tingkat Proyek: .claude/settings.json di ruang kerja saat ini
- Tingkat Pengguna: ~/.claude/settings.json untuk semua sesi
- Disediakan Plugin: Hook yang dibundel dengan plugin yang terpasang
Hook tingkat proyek mengganti hook pengguna untuk peristiwa yang sama. Ini memungkinkan aturan pemformatan khusus proyek sambil mempertahankan handler notifikasi global.
Pola Pencocok untuk Eksekusi Selektif
Sistem pencocok memfilter hook ke alat atau kondisi tertentu. Tanpa pencocok, hook aktif untuk setiap kejadian peristiwanya.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Bidang pathPattern menerima sintaks glob. Bidang toolName cocok dengan alat bawaan Claude seperti edit_file, execute_command, read_file, dan create_directory.
Diskusi komunitas mengungkapkan bahwa kombinasi pencocok bekerja dengan logika AND. Semua pencocok yang ditentukan harus cocok agar hook dieksekusi.
Hook Perintah: Integrasi Skrip Shell
Hook perintah mengeksekusi perintah atau skrip shell dengan input JSON terstruktur. Hook ini mewakili jenis hook yang paling umum untuk otomatisasi lokal.
Dokumentasi resmi menyatakan bahwa hook perintah menerima JSON melalui stdin dengan struktur ini:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skrip mengurai input ini untuk membuat keputusan. Hook validasi Python mungkin terlihat seperti:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Tidak dapat mengedit file yang dilindungi”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Kode keluar 0 mengizinkan operasi. Kode keluar 1 memblokirnya dan menampilkan pesan stderr ke Claude. Kode keluar 2 memicu perilaku khusus tergantung pada peristiwa.
Perilaku Kode Keluar 2
Menurut dokumentasi referensi hook resmi, kode keluar 2 memiliki makna khusus peristiwa (PreToolUse: memblokir dan meminta pertimbangan ulang; UserPromptSubmit: memberikan konteks tanpa memblokir; PermissionRequest: memblokir izin):
- PreToolUse: Memblokir alat dan meminta Claude untuk mempertimbangkan kembali dengan pesan stderr sebagai konteks
- UserPromptSubmit: Memberikan keluaran stderr sebagai konteks tambahan tanpa memblokir
- PermissionRequest: Memblokir pemberian izin
Ini menciptakan jalan tengah antara pemblokiran keras dan pengizinan. Claude menerima umpan balik tentang mengapa tindakan tersebut mungkin bermasalah dan dapat menyesuaikan pendekatannya.
Hook Perintah Asinkron
Bendera async: true menjalankan hook di latar belakang tanpa memblokir alur kerja Claude. Ini penting untuk operasi yang lambat seperti notifikasi penyebaran atau pengumpulan metrik.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Ketika hook asinkron aktif, Claude Code memulai proses dan melanjutkan segera. Bidang timeout mengatur waktu eksekusi maksimum dalam detik. Jika tidak ditentukan, hook asinkron menggunakan batas waktu default 10 menit.
Pembicaraan nyata: hook asinkron tidak dapat memblokir operasi karena berjalan setelah Claude melanjutkan. Hook ini berfungsi untuk pencatatan, notifikasi, dan pembersihan—bukan validasi.
Hook HTTP: Integrasi Layanan Eksternal
Hook HTTP memposting muatan JSON ke titik akhir jarak jauh dan mengurai respons untuk kontrol keputusan. Hook ini memungkinkan integrasi dengan layanan validasi, database, dan alat pihak ketiga.
Konfigurasi hook HTTP dasar:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktur muatan cocok dengan input hook perintah tetapi tiba sebagai badan POST HTTP. Respons menentukan tindakan Claude selanjutnya.
Penanganan Respons HTTP
Menurut dokumentasi resmi, hook HTTP menafsirkan respons berdasarkan kode status dan konten badan:
| Kode Status | Efek | Sumber Pesan |
|---|---|---|
| 200 | Izinkan operasi | Badan respons (opsional) |
| 400 | Blokir operasi | Badan respons ditampilkan ke Claude |
| 500 | Kesalahan hook, izinkan operasi | Dicatat tetapi tidak ditampilkan ke Claude |
| Lainnya | Izinkan operasi | Kegagalan hook tidak memblokir alur kerja |
Badan respons dapat menyertakan bidang pesan yang dilihat Claude sebagai konteks. Ini memungkinkan layanan validasi untuk menjelaskan mengapa operasi diblokir.
Interpolasi Variabel Lingkungan
Hook HTTP mendukung sintaks ${VAR} di url, headers, dan bidang string lainnya. Variabel diperluas dari lingkungan tempat Claude Code berjalan.
Menurut dokumentasi MCP resmi, ekspansi variabel lingkungan mencakup sintaks fallback default: ${VAR:-default} diperluas ke VAR jika diatur, jika tidak, gunakan nilai default.
Kendala keamanan: Menurut masalah GitHub #28044, hook HTTP hanya dapat mengakses variabel lingkungan yang secara eksplisit terdaftar dalam bidang konfigurasi allowedEnvVars. Ini mencegah eksposur kredensial yang tidak disengaja.
Hook Prompt: Injeksi Konteks
Hook prompt menyuntikkan instruksi dinamis ke dalam konteks Claude pada peristiwa tertentu. Hook ini memodifikasi perilaku tanpa proses eksternal atau panggilan API.
| { “event”: “SessionStart”, “prompt”: “Anda sedang mengerjakan proyek TypeScript. Selalu gunakan pemeriksaan null yang ketat dan utamakan async/await daripada promise.” } |
Teks yang disuntikkan menjadi bagian dari instruksi sistem Claude untuk sesi tersebut. Hook prompt juga dapat menggunakan variabel template yang diperluas berdasarkan data peristiwa.
Pembuatan Prompt Dinamis
Menurut dokumentasi resmi, hook prompt mendukung bidang perintah yang menghasilkan prompt dinamis:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Perintah menerima input JSON standar melalui stdin dan mengeluarkan teks prompt ke stdout. Ini memungkinkan pembuatan instruksi yang sadar konteks berdasarkan keadaan proyek.
Hook Berbasis Agen
Hook agen menentukan sub-agen yang menangani peristiwa alih-alih injeksi prompt langsung. Sub-agen menerima konteks tentang peristiwa dan dapat melakukan penalaran multi-langkah.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Panggilan alat gagal. Analisis kesalahannya dan sarankan perbaikannya.” } |
Sub-agen bernama harus ditentukan dalam konfigurasi proyek. Hook agen memungkinkan logika keputusan yang kompleks yang tidak dapat disediakan oleh injeksi prompt sederhana.
Pola Hook Praktis
Diskusi komunitas dan contoh resmi mengungkapkan pola otomatisasi spesifik yang berfungsi andal di produksi.
Format Otomatis Kode Setelah Pengeditan
Pola yang paling umum memformat kode secara otomatis setelah Claude mengedit file:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Variabel ${toolInput.path} diperluas ke jalur file yang diedit. PostToolUse memastikan pemformatan terjadi setelah pengeditan yang berhasil tetapi tidak memblokir alur kerja Claude.
Blokir Modifikasi File yang Dilindungi
Hook PreToolUse menegakkan aturan perlindungan file:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skrip memvalidasi jalur target terhadap pola yang dilindungi dan keluar dengan kode 1 untuk memblokir pengeditan yang dilarang.
Dapatkan Notifikasi Saat Claude Membutuhkan Input
Menurut panduan alur kerja resmi, hook Notifikasi dapat memicu peringatan desktop atau mengirim pesan ke layanan eksternal:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Ini aktif setiap kali Claude Code mengirimkan notifikasi, termasuk saat menunggu input pengguna atau setelah penyelesaian tugas.
Masukkan Kembali Konteks Setelah Kompaksi
Hook ContextCompaction memulihkan konteks penting saat jendela percakapan penuh:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Keluaran perintah disuntikkan kembali ke dalam konteks Claude setelah kompaksi menghapus pesan yang lebih lama. Ini mencegah hilangnya instruksi penting khusus proyek.
Audit Perubahan Konfigurasi
Lacak kapan Claude memodifikasi file konfigurasi:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Eksekusi asinkron mencegah Claude terblokir saat operasi git selesai. Ini menciptakan jejak audit perubahan konfigurasi tanpa penahapan manual.
Output JSON dan Kontrol Keputusan
Hook perintah dapat mengeluarkan JSON terstruktur untuk memberikan umpan balik terperinci di luar kode keluar sederhana. Menurut referensi resmi, output JSON memungkinkan respons multi-bidang yang ditafsirkan Claude untuk pengambilan keputusan.
| { “allowed”: false, “message”: “File ini dilindungi oleh kebijakan tim”, “suggestion”: “Buat file baru di src/features/ sebagai gantinya” } |
Bidang allowed mengontrol apakah operasi dilanjutkan. Pesan ditampilkan ke Claude sebagai konteks. Bidang suggestion memberikan pendekatan alternatif.
Agar hook mengeluarkan JSON, mereka harus:
- Menulis JSON yang valid ke stdout
- Keluar dengan kode 0 (untuk diizinkan) atau 1 (untuk diblokir)
- Sertakan setidaknya bidang boolean allowed
Claude Code mengurai JSON dan menggunakannya untuk meningkatkan loop umpan balik. Kode keluar masih menentukan keputusan utama, tetapi JSON memberikan konteks yang lebih kaya.
Referensi Bidang Input Hook
Semua hook menerima objek JSON melalui stdin dengan bidang umum ditambah data spesifik peristiwa. Memahami skema lengkap memungkinkan logika hook yang lebih canggih.
Bidang Input Umum
Setiap hook menerima bidang dasar ini:
- event: Nama peristiwa hook (misalnya, "PreToolUse")
- sessionId: Pengenal unik untuk sesi Claude saat ini
- turnId: Pengenal untuk giliran percakapan saat ini
- timestamp: Cap waktu ISO 8601 saat peristiwa aktif
Bidang Peristiwa Alat
Peristiwa PreToolUse, PostToolUse, dan PostToolUseFailure mencakup:
- toolName: Nama alat yang dipanggil (edit_file, execute_command, dll.)
- toolInput: Objek yang berisi parameter input alat
- toolResponse: Data keluaran alat (hanya PostToolUse)
- error: Detail kesalahan termasuk pesan dan kode (hanya PostToolUseFailure)
Struktur toolInput bervariasi berdasarkan alat. Untuk edit_file, ini berisi path dan konten. Untuk execute_command, ini berisi perintah dan argumen.
Bidang Peristiwa Izin
Peristiwa PermissionRequest mencakup:
- permissionType: Jenis izin yang diminta (file_write, command_execute, dll.)
- requestedAction: Tindakan spesifik yang memerlukan izin
- resourcePath: Jalur file atau pengenal sumber daya yang terpengaruh
Hook Alat MCP
Menurut referensi hook resmi, hook dapat cocok dengan alat Model Context Protocol (MCP) menggunakan bidang pencocok mcpTool. Ini memungkinkan eksekusi hook saat Claude menggunakan alat eksternal yang disediakan oleh server MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Nilai mcpTool cocok dengan nama alat dalam format server-name/tool-name. Ini memungkinkan logika validasi untuk kueri database, panggilan API, atau operasi eksternal lainnya.
Permintaan fitur GitHub menunjukkan minat yang berkembang dalam integrasi MCP yang lebih dalam, termasuk hook yang dapat memeriksa notifikasi server MCP dan merespons peristiwa eksternal.
Pertimbangan Keamanan
Hook dieksekusi dengan izin yang sama dengan Claude Code itu sendiri. Ini menciptakan implikasi keamanan untuk lingkungan multi-pengguna dan konfigurasi bersama.
Sandbox Eksekusi Perintah
Menurut masalah GitHub #28044, hook HTTP dirutekan melalui proxy sandbox yang membatasi akses jaringan dan memfilter variabel lingkungan. Hook perintah tidak memiliki batasan seperti itu—hook dieksekusi dengan akses shell penuh.
Dokumentasi merekomendasikan praktik-praktik ini:
- Jangan pernah menyimpan kredensial dalam perintah hook
- Gunakan variabel lingkungan untuk data sensitif
- Validasi semua input dari ekspansi ${…}
- Implementasikan batas waktu untuk layanan eksternal
- Gunakan hook asinkron untuk operasi non-kritis untuk mencegah pemblokiran pada kegagalan
Isolasi Eksekusi Hook
Hook tingkat pengguna di ~/.claude/settings.json berlaku untuk semua proyek. Ini menciptakan risiko saat bekerja di berbagai batas kepercayaan. Hook tingkat proyek mengganti hook pengguna tetapi tidak dapat sepenuhnya menonaktifkannya.
Menu /hooks di Claude Code menampilkan semua hook aktif untuk sesi saat ini. Meninjau daftar ini sebelum mengerjakan proyek sensitif membantu mengidentifikasi potensi masalah keamanan.
Debugging dan Pemecahan Masalah
Kegagalan hook tidak selalu muncul dengan jelas dalam percakapan Claude. Dokumentasi resmi menyediakan beberapa pendekatan debugging.
Log Eksekusi Hook
Claude Code mencatat eksekusi hook ke keluaran debug sesi. Menurut panduan pemecahan masalah, mengaktifkan logging debug mengungkapkan:
- Hook mana yang cocok untuk setiap peristiwa
- Input JSON yang dikirim ke setiap hook
- Keluaran stdout dan stderr dari proses hook
- Kode keluar dan waktu eksekusi
- Kode dan badan respons HTTP untuk hook HTTP
Aktifkan debug logging dengan mengatur CLAUDE_DEBUG=1 di lingkungan sebelum memulai Claude Code.
Menguji Hook Secara Independen
Hook perintah dapat diuji di luar Claude Code dengan membuat input JSON secara manual:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Ini memvalidasi logika hook tanpa memicu operasi Claude yang sebenarnya. Kode keluar dan keluaran stdout/stderr harus cocok dengan perilaku yang diharapkan.
Kegagalan Hook Umum
Diskusi komunitas mengidentifikasi masalah umum ini:
- Kesalahan batas waktu: Batas waktu default 10 menit terlalu singkat untuk operasi yang lambat—tingkatkan dengan bidang timeout
- Kegagalan ekspansi jalur: Variabel seperti ${file} tidak terdefinisi untuk peristiwa yang tidak menyertakan konteks file
- Kesalahan izin: Skrip hook tidak memiliki izin eksekusi—jalankan chmod +x script.sh
- Kesalahan parse JSON: Keluaran JSON yang rusak dari hook—validasi dengan jq sebelum mengembalikan
- Ketidaktersediaan variabel lingkungan: Variabel tidak disebarkan ke proses hook—periksa lingkungan Claude Code
Implikasi Kinerja Hook
Hook sinkron memblokir alur kerja Claude hingga selesai. Batas waktu default 10 menit mencegah hang tak terbatas, tetapi bahkan penundaan singkat terakumulasi di berbagai operasi.
Praktisi melaporkan bahwa hook validasi sederhana memiliki dampak kinerja yang dapat diabaikan. Hook pemformatan file menyebabkan dampak kinerja yang terlihat tetapi dapat diterima. Panggilan API eksternal dapat menciptakan gesekan alur kerja. Operasi komputasi berat mendapat manfaat dari eksekusi asinkron.
Batching Hook
Beberapa hook dapat cocok dengan peristiwa yang sama. Menurut dokumentasi referensi, hook dieksekusi secara berurutan dalam urutan definisi. Jika ada hook yang memblokir operasi, hook yang tersisa tidak dieksekusi.
Ini penting untuk kinerja. Lima hook sinkron masing-masing 200ms menambahkan satu detik per peristiwa. Menggabungkan validasi terkait ke dalam satu hook mengurangi overhead.
Pola Lanjutan
Di luar otomatisasi dasar, hook memungkinkan penyesuaian alur kerja yang canggih.
Rantai Hook dengan Keadaan
Hook dapat mempertahankan keadaan antar eksekusi menggunakan file atau database. Hook PostToolUse dapat mencatat operasi yang berhasil yang kemudian divalidasi oleh hook PreToolUse terhadapnya:
| #!/bin/bash # Catat pengeditan yang berhasil echo “${toolInput.path}” >> .claude/edit-history.txt |
Hook PreToolUse pendamping dapat memeriksa riwayat ini untuk mencegah operasi yang berlebihan atau menegakkan batasan urutan.
Aktivasi Hook Bersyarat
Variabel lingkungan mengontrol perilaku hook saat runtime. Mengatur CLAUDE_SKIP_HOOKS=1 menonaktifkan hook untuk situasi darurat.
Hook itu sendiri dapat memeriksa flag lingkungan:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Terapkan validasi ketat exit 1 fi exit 0 |
Ini memungkinkan perilaku mode pengembangan versus mode produksi tanpa perubahan konfigurasi.
Validasi Multi-Tahap
Hook PreToolUse dapat mengimplementasikan validasi multi-tingkat di mana kode keluar 2 memungkinkan Claude untuk melanjutkan dengan peringatan:
- Kegagalan keras (keluar 1): Blokir operasi berbahaya
- Peringatan lunak (keluar 2): Beri tahu Claude untuk mempertimbangkan kembali
- Lulus dengan konteks (keluar 0 + JSON): Berikan informasi tambahan
Ini menciptakan spektrum validasi yang lebih bernuansa daripada biner izinkan/tolak.
Integrasi dengan CI/CD
Menurut dokumentasi integrasi platform resmi, Claude Code berjalan di lingkungan CI/CD untuk peninjauan kode otomatis dan triase masalah. Hook memperluas otomatisasi ini.
Alur kerja GitHub Actions dapat menentukan hook yang menegakkan kebijakan tim selama sesi otomatis:
| – name: Jalankan Claude Code dengan hook ketat env: STRICT_MODE: 1 run: | claude “Tinjau PR ini dan sarankan perbaikan” |
Bendera STRICT_MODE mengaktifkan logika validasi bersyarat dalam skrip hook. Ini memastikan sesi otomatis mengikuti aturan yang lebih ketat daripada pengembangan interaktif.
Pembuatan Jejak Audit
Hook PostToolUse di lingkungan CI membuat log audit terperinci dari semua operasi Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Pencatatan latar belakang tidak memengaruhi kinerja tetapi menyediakan riwayat operasi lengkap untuk kepatuhan dan debugging.
Menu /hooks
Claude Code menyediakan perintah /hooks yang menampilkan semua hook aktif untuk sesi saat ini. Menurut dokumentasi resmi, menu ini menampilkan:
- Jenis peristiwa hook
- Pola pencocok
- Titik akhir perintah atau URL
- Apakah hook berjalan secara asinkron
- Sumber konfigurasi (proyek, pengguna, atau plugin)
Memilih hook akan menampilkan konfigurasi lengkapnya dan memungkinkan penonaktifan sementara untuk sesi saat ini.
Nonaktifkan atau Hapus Hook
Hook dapat dinonaktifkan tanpa menghapus konfigurasi dengan menambahkan "enabled": false ke definisi hook. Ini mempertahankan konfigurasi sambil mencegah eksekusi.
Untuk menghapus hook secara permanen, hapus entri dari file settings.json yang sesuai. Perubahan berlaku pada restart sesi berikutnya atau saat menjalankan /reload.
Hook dalam Keterampilan dan Agen
Menurut dokumentasi resmi, hook yang ditentukan dalam konfigurasi keterampilan atau sub-agen hanya berlaku saat keterampilan atau agen tersebut dieksekusi. Ini memungkinkan otomatisasi khusus untuk alur kerja tertentu.
Sub-agen debugging mungkin menyertakan hook yang mencatat semua panggilan alat:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Hook ini hanya aktif selama sesi agen debugger, bukan selama operasi Claude Code normal.
Referensi Skrip Berdasarkan Jalur
Perintah hook mendukung jalur relatif dan absolut. Jalur relatif diselesaikan dari akar proyek tempat Claude Code berjalan.
Praktik terbaik dari diskusi komunitas:
- Simpan skrip hook di direktori .claude/hooks/
- Gunakan nama deskriptif: validate-typescript.sh bukan hook1.sh
- Buat skrip dapat dieksekusi: chmod +x .claude/hooks/*.sh
- Sertakan baris shebang: #!/usr/bin/env bash atau #!/usr/bin/env python3
- Tambahkan penanganan kesalahan dengan set -e dalam skrip bash
Kemampuan Hook di Masa Depan
Permintaan fitur GitHub mengungkapkan peningkatan hook yang direncanakan dan diminta:
- Hook skrip inline: Tentukan logika hook langsung di settings.json tanpa file eksternal
- Integrasi alat MCP: Panggil alat server MCP dari hook alih-alih perintah shell
- Kolaborasi multi-agen: Hook yang berkoordinasi antar instance Claude di mesin yang berbeda
- Pengetikan yang ditingkatkan: Definisi tipe TypeScript untuk skema input/output hook
Menurut masalah GitHub #4274, permintaan untuk jenis hook terintegrasi (alat MCP, skrip inline, panggilan API) bertujuan untuk menyederhanakan konfigurasi dan meningkatkan pengalaman pengembang.
Pertanyaan yang Sering Diajukan
Dapatkah hook mencegah Claude mengeksekusi perintah berbahaya?
Ya. Hook PreToolUse dapat memblokir eksekusi alat apa pun dengan keluar dengan kode 1. Ini termasuk pengeditan file, eksekusi perintah, dan panggilan alat MCP. Hook menerima input alat lengkap dan dapat memvalidasi terhadap kriteria apa pun sebelum mengizinkan operasi.
Bagaimana cara men-debug hook yang tidak berfungsi?
Aktifkan logging debug dengan CLAUDE_DEBUG=1 sebelum memulai Claude Code. Periksa log sesi untuk detail eksekusi hook termasuk hook mana yang cocok, input JSON yang dikirim, keluaran stdout/stderr, dan kode keluar. Uji hook secara independen dengan mem-pipe JSON sampel ke skrip hook.
Apakah hook berfungsi dengan semua platform Claude Code?
Hook berfungsi di CLI, aplikasi desktop, dan ekstensi VS Code. Menurut dokumentasi resmi, hook dieksekusi di mana pun Claude Code berjalan dengan akses ke sistem file. Claude berbasis browser dan aplikasi seluler tidak mendukung hook karena kendala sandboxing.
Dapatkah hook memodifikasi respons atau perilaku Claude?
Hook prompt menyuntikkan instruksi yang memengaruhi perilaku Claude. Hook agen mendelegasikan penanganan peristiwa ke sub-agen khusus. Namun, hook tidak dapat secara langsung memodifikasi teks yang dihasilkan atau proses penalaran Claude—hook bekerja dengan memberikan konteks dan memblokir operasi.
Apa perbedaan antara hook asinkron dan sinkron?
Hook sinkron memblokir alur kerja Claude hingga selesai atau batas waktu. Hook asinkron berjalan di latar belakang tanpa memblokir. Hook sinkron dapat mencegah operasi melalui kode keluar. Hook asinkron tidak dapat memblokir karena Claude melanjutkan sebelum hook selesai. Gunakan asinkron untuk pencatatan dan notifikasi, sinkron untuk validasi.
Bagaimana cara berbagi hook di seluruh tim?
Simpan file .claude/settings.json ke kontrol versi. Hook tingkat proyek berlaku untuk semua anggota tim yang mengkloning repositori. Untuk kebijakan di seluruh organisasi, tim dapat memelihara file pengaturan tingkat pengguna bersama yang disalin anggota ke ~/.claude/settings.json.
Bisakah hook HTTP memanggil API internal di belakang firewall?
Ya, jika Claude Code berjalan di lingkungan dengan akses jaringan ke API tersebut. Hook HTTP membuat permintaan POST standar dari mesin yang menjalankan Claude Code. Firewall perusahaan dan VPN berlaku secara normal. Proxy sandbox yang disebutkan dalam dokumentasi mengontrol paparan variabel lingkungan, bukan perutean jaringan.
Apakah hook meningkatkan penggunaan token Claude Code?
Hook prompt menyuntikkan teks ke dalam konteks Claude, yang mengonsumsi token. Hook perintah dan HTTP tidak secara langsung memengaruhi penggunaan token, tetapi keluaran mereka (pesan kesalahan, saran) menjadi bagian dari konteks percakapan. Kode keluar 2 dengan pesan penjelasan menambahkan lebih banyak konteks daripada kode keluar 1 dengan pemblokiran sederhana.
Kesimpulan
Hook Claude Code mengubah asisten AI dari alat yang ampuh menjadi platform pengembangan yang sepenuhnya otomatis. Sistem peristiwa menyediakan titik intersepsi di seluruh alur kerja Claude—mulai dari inisialisasi sesi hingga kompaksi konteks.
Hook perintah menangani validasi dan pemformatan lokal. Hook HTTP mengintegrasikan layanan dan database eksternal. Hook prompt memodifikasi perilaku melalui injeksi konteks. Bersama-sama, ini memungkinkan pola otomatisasi yang menegakkan kebijakan tim, menjaga kualitas kode, dan terintegrasi dengan infrastruktur pengembangan yang ada.
Sistem pencocok memfilter hook ke alat dan pola file tertentu. Kode keluar dan keluaran JSON mengontrol alur keputusan. Eksekusi asinkron mencegah pemblokiran pada operasi yang lambat. Skema konfigurasi lengkap mendukung segalanya mulai dari pemformatan otomatis sederhana hingga validasi multi-tahap yang kompleks.
Mulailah dengan hook PostToolUse dasar untuk pemformatan kode. Tambahkan validasi PreToolUse saat kebijakan muncul. Bereksperimenlah dengan hook prompt untuk modifikasi perilaku. Bangun integrasi HTTP untuk penegakan kebijakan di seluruh tim.
Periksa dokumentasi resmi Claude Code untuk referensi hook lengkap dan skema konfigurasi yang diperbarui seiring dengan dirilisnya kemampuan baru.
