Claude Code Hooks: Panduan Power-User untuk Mengotomatiskan Agent Anda

Hooks Claude Code adalah perintah yang ditentukan pengguna dan berjalan secara otomatis pada titik-titik tertentu dalam siklus hidup Claude Code — sebelum panggilan tool, setelah edit, saat sesi dimulai, saat Claude menyelesaikan giliran — sehingga Anda dapat memvalidasi, memformat, mencatat log, atau memblokir tindakan tanpa harus terlibat langsung setiap saat. Inilah yang membedakan agen coding AI yang hanya menyarankan dengan yang mengikuti aturan Anda secara deterministik. Panduan ini menjelaskan apa itu hooks, setiap event yang dapat memicunya, cara mengonfigurasinya, lima resep praktis yang dapat Anda salin, jebakan exit-code yang sering membuat orang salah paham, dan cara menggunakan kekuatan penuh Claude Code tanpa pengaturan lokal apa pun.

Apa Itu Claude Code Hooks?

Hook adalah handler — sebuah shell command, endpoint HTTP, panggilan tool MCP, atau bahkan prompt model — yang dijalankan Claude Code secara otomatis ketika event tertentu terjadi. Handler menerima input terstruktur (melalui stdin untuk command hooks, atau sebagai POST body untuk HTTP hooks), dapat memeriksa apa yang sedang terjadi, mengambil tindakan, dan secara opsional mengembalikan keputusan yang mengubah langkah Claude selanjutnya.

Bagian terakhir itulah yang membuat hooks menjadi kuat, bukan sekadar praktis. Hook bukan hanya notifikasi — hook dapat memblokir panggilan tool, menulis ulang input atau output tool, menyisipkan konteks tambahan, atau menghentikan Claude sepenuhnya. Dengan kata lain, hooks mengubah Claude Code dari asisten pintar menjadi asisten yang dapat diprogram, yang menegakkan pagar pembatas tim Anda secara deterministik, bukan hanya saat model kebetulan mengingatnya.

Kapan Hooks Terpicu: Siklus Hidup

Hooks terpasang pada event, dan Claude Code menyediakan banyak sekali di antaranya. Hooks dikelompokkan berdasarkan frekuensi: ada yang terpicu sekali per sesi, ada yang sekali per giliran, dan ada yang setiap kali ada panggilan tool.

Di mana hooks terpicu sepanjang sesi Claude Code — dari SessionStart hingga SessionEnd.

Event yang paling sering Anda gunakan:

• SessionStart / SessionEnd — sekali ketika sesi dimulai atau berakhir. Sangat cocok untuk memuat konteks (isu terbuka, info branch, variabel environment) atau pembersihan.
• UserPromptSubmit — terpicu saat Anda mengirimkan prompt, sebelum Claude memprosesnya. Anda dapat memfilter atau menambah prompt.
• PreToolUse — sebelum panggilan tool apa pun. Di sinilah Anda memblokir tindakan berbahaya.
• PostToolUse (dan PostToolUseFailure) — setelah panggilan tool berhasil (atau gagal). Tempat untuk linting, formatting, dan verifikasi.
• Stop / StopFailure — ketika Claude selesai merespons, atau giliran berakhir karena error.
• Notification — ketika Claude Code mengirim notifikasi (berguna untuk peringatan desktop).

Selain itu, Claude Code juga memicu hooks untuk subagent (SubagentStart/SubagentStop), task (TaskCreated/TaskCompleted), kompaksi konteks (PreCompact/PostCompact), perubahan working-directory (CwdChanged), perubahan file di disk (FileChanged), pemuatan instruksi (InstructionsLoaded), dan lainnya. Keluasan inilah intinya: hampir setiap momen dalam loop agen adalah tempat Anda dapat menempelkan kebijakan.

Lima Jenis Handler Hook

Sebuah event hook dapat memicu lima jenis handler yang berbeda, dan inilah yang membuat sistem ini fleksibel:

1. command — menjalankan shell command; membaca input melalui stdin, mengirimkan keputusan lewat exit code dan stdout.
2. http — mengirim POST berisi JSON event ke URL dan membaca respons JSON.
3. mcp_tool — memanggil tool pada server MCP yang terhubung.
4. prompt — evaluasi model satu giliran yang mengembalikan keputusan JSON ya/tidak (berguna untuk pemeriksaan yang bersifat fuzzy).
5. agent — memunculkan subagent (eksperimental).

Bagi kebanyakan tim, hooks command sudah mencakup 90% kebutuhan — sebuah shell script sudah cukup untuk melakukan lint, blokir, atau log.

Cara Mengonfigurasi Hook

Hooks berada di file settings (dokumentasi resmi Claude Code hooks adalah referensi utamanya), dan lokasi penempatannya menentukan cakupannya:

Strukturnya bertingkat tiga level: pilih sebuah event, tambahkan grup matcher, lalu tentukan handlers. Matcher menentukan panggilan tool mana yang berlaku untuk suatu hook — "*" (atau tanpa menuliskannya) mencocokkan semuanya, Edit|Write yang sederhana mencocokkan tool-tool tersebut secara eksak, dan apa pun yang lebih kompleks diperlakukan sebagai regular expression. (Tool MCP mencocokkan pola mcp__<server>__<tool>.)

Berikut adalah hook PostToolUse yang menjalankan pemeriksaan lint setelah setiap edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Lima Resep Hook Praktis

Berikut pola-pola yang paling sering digunakan tim:

1. Lint atau format setelah setiap edit. Hook PostToolUse yang dicocokkan dengan Edit|Write, menjalankan formatter atau linter Anda, sehingga kode agen selalu memenuhi aturan gaya penulisan Anda.
2. Memblokir command yang destruktif. Hook PreToolUse yang dicocokkan dengan Bash, memeriksa command tersebut dan memblokir rm -rf dan sejenisnya sebelum sempat dijalankan.
3. Notifikasi desktop. Hook Notification yang memberi tahu Anda saat Claude membutuhkan perhatian atau menyelesaikan tugas panjang.
4. Audit logging. Hook PostToolUse (atau yang ditargetkan ke MCP) yang mencatat log setiap panggilan tool untuk keperluan compliance — apa yang berjalan, kapan, dan dengan argumen apa.
5. Memuat konteks proyek saat startup. Hook SessionStart yang menarik isu terbuka, branch saat ini, atau variabel environment, sehingga agen mulai setiap sesi sudah dalam kondisi terarah.

Lima resep hook yang umum digunakan dan event tempat mereka terpasang.

Jebakan Exit-Code

Inilah detail yang sering membuat orang salah paham, jadi pahami baik-baik: untuk hooks command, hanya exit code 2 yang memblokir. Exit 0 berarti sukses (dan stdout diparsing untuk keputusan JSON apa pun). Exit 2 adalah error yang blocking — stderr-nya dikirim kembali ke Claude. Kode lain apa pun, termasuk exit 1, adalah error non-blocking — Claude tetap melanjutkan.

Jadi, jika Anda menulis hook "blokir ini" dan menggunakan exit 1, hook tersebut tidak akan memblokir — tindakan tetap berlanjut. Untuk benar-benar menegakkan kebijakan dari sebuah command hook, gunakan exit 2. (Command hooks juga dapat mengembalikan kontrol yang lebih kaya sebagai JSON pada stdout — permissionDecision: "deny" untuk PreToolUse, updatedInput untuk menulis ulang argumen, additionalContext untuk menyisipkan informasi, dan continue: false untuk menghentikan Claude sepenuhnya.)

Contoh Praktis: Memblokir rm -rf

Mari kita bangun pengaman command destruktif ini secara utuh, karena ini menunjukkan setiap bagian yang bergerak. Pertama, konfigurasinya — hook PreToolUse yang dicocokkan dengan Bash:

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Kemudian scriptnya, guard.sh. Claude Code mengirim event sebagai JSON melalui stdin, termasuk input tool tersebut; script membacanya, memeriksa command-nya, dan mengambil keputusan:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

Baris yang menentukan adalah exit 2. Kembalikan 0 dan command akan berjalan; kembalikan 1 dan — secara berlawanan dengan intuisi — command tersebut tetap berjalan sebagai error non-blocking; hanya exit 2 yang memblokir dan mengirim pesan stderr Anda kembali ke Claude sehingga ia memahami alasannya. Jadikan script tersebut executable, commit di bawah .claude/hooks/, dan setiap panggilan Bash sekarang melewati pengaman Anda — untuk seluruh tim Anda, karena settings.json di level proyek dapat dibagikan. Untuk garansi yang benar-benar pasti daripada sekadar jaring pengaman terbaik yang bisa diusahakan, padukan ini dengan aturan izin (permission rules) Claude Code; sebagai jaring pengaman yang deterministik dan terkontrol versi, hook ini sudah menjalankan tugasnya.

Kapan Hooks Bukan Jawabannya

Hooks ditujukan untuk kebijakan yang deterministik dan berulang — "selalu lint setelah edit," "jangan pernah jalankan rm -rf." Hooks adalah alat yang salah untuk hal-hal yang membutuhkan penilaian (gunakan model atau hook prompt untuk keputusan yang bersifat fuzzy) dan untuk garansi keamanan yang keras (gunakan sistem izin, karena filter if pada command-hook gagal secara terbuka/fail open). Jangan juga berlebihan menggunakan hook: setiap command hook menjalankan proses dengan timeout, dan sekumpulan hook yang lambat akan menambah latensi pada setiap panggilan tool. Buat hooks tetap cepat, sedikit jumlahnya, dan fokus pada aturan yang benar-benar penting.

Catatan Keamanan yang Perlu Diketahui

Beberapa fakta yang secara eksplisit dinyatakan dalam dokumentasi:

• Filter if gagal secara terbuka (fails open). Jika Anda menggunakan field if untuk membatasi cakupan hook pada suatu aturan izin dan command tidak dapat diparsing, hook tetap berjalan. Untuk penegakan izin/tolak yang ketat, gunakan sistem izin Claude Code, bukan hooks.
• Hooks berjalan tanpa terminal pengontrol — mereka tidak dapat menampilkan prompt pada /dev/tty. Gunakan systemMessage atau output terminalSequence yang terbatas untuk pesan yang ditampilkan kepada pengguna.
• Stdout harus bersih. Hanya objek keputusan JSON yang boleh ada di stdout; output shell-profile yang tidak sengaja muncul bisa merusak proses parsing.
• Perlakukan konteks yang disisipkan dengan hati-hati. additionalContext sebaiknya ditulis sebagai pernyataan faktual, bukan perintah imperatif, agar selaras dengan pertahanan terhadap prompt-injection.

Hooks Adalah Miniatur dari Harness Engineering

Mundur sejenak, hooks adalah contoh konkret dari gagasan yang lebih besar: model bukanlah keseluruhan agen — sistem di sekitarnyalah yang menentukan. Hooks adalah bagian dari harness yang membuat agen coding menjadi andal, berdampingan dengan loop, tools, memory, dan sandbox. (Kami membahas model mental ini secara mendalam dalam harness engineering.) Saat Anda menulis blokir PreToolUse atau linter PostToolUse, Anda sedang melakukan harness engineering — membentuk perilaku agen secara deterministik daripada hanya berharap model berperilaku sebagaimana yang diinginkan.

Kerangka pemikiran ini juga memberi tahu Anda kapan hooks layak diusahakan: aturan apa pun yang harus Anda ingatkan berulang kali kepada agen adalah kandidat yang tepat untuk sebuah hook.

Menggunakan Kekuatan Penuh Claude Code Tanpa Pengaturan Lokal

Hooks berada di dalam Claude Code CLI, yang berarti Anda perlu menginstal dan mengonfigurasinya untuk dapat menggunakan hooks — sebuah penghalang bagi siapa pun yang belum terbiasa dengan terminal, dan mustahil bagi rekan tim non-developer. Jika Anda menginginkan kemampuan agen Claude Code tanpa harus mengelola instalasi lokal, Anda dapat menjalankan Claude Code di browser Anda di Happycapy: platform ini menjalankan Claude Code dalam managed cloud sandbox, tempat harness — loop, tools, memory, dan isolasi yang menjadi tempat hooks terpasang — sudah disiapkan untuk Anda. Anda cukup menjelaskan sebuah tugas dan menyaksikan agen bekerja pada desktop visual, tanpa memerlukan terminal.

Bayangkan seperti ini: hooks memungkinkan pengguna tingkat lanjut untuk menyesuaikan harness Claude Code secara manual; Happycapy memberikan setiap orang harness terkelola secara langsung. Jika Anda ingin memanfaatkan Claude Code tetapi terhalang oleh proses setup CLI, mulai gratis di happycapy.ai dan jalankan tugas nyata di browser Anda hari ini.

Pertanyaan yang Sering Diajukan

T: Apa itu Claude Code hooks?

Hooks adalah handler yang ditentukan pengguna — shell command, endpoint HTTP, panggilan tool MCP, atau prompt model — yang dijalankan Claude Code secara otomatis pada event siklus hidup seperti sebelum panggilan tool (PreToolUse), setelah edit (PostToolUse), atau saat sesi dimulai. Hooks dapat memvalidasi, memformat, mencatat log, memblokir, atau menulis ulang tindakan.

T: Event hook apa saja yang didukung Claude Code?

Banyak sekali — termasuk SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (dan PostToolUseFailure), Stop/StopFailure, Notification, event subagent dan task, serta event kompaksi. Event-event ini terpicu sekali per sesi, sekali per giliran, atau setiap kali ada panggilan tool.

T: Bagaimana cara membuat hook memblokir panggilan tool?

Untuk command hooks, keluar (exit) dengan kode 2 — hanya exit 2 yang memblokir (exit 1 tidak). Untuk PreToolUse, Anda juga dapat mengembalikan JSON dengan permissionDecision: "deny". Untuk penegakan yang benar-benar ketat, lebih baik gunakan sistem izin Claude Code, karena filter if pada hook gagal secara terbuka.

T: Di mana saya mengonfigurasi Claude Code hooks?

Di file settings: ~/.claude/settings.json (semua proyek), .claude/settings.json (satu proyek, dapat dibagikan), atau .claude/settings.local.json (hanya lokal). Anda memilih sebuah event, menambahkan matcher, dan menentukan handlers.

T: Bisakah saya menggunakan Claude Code hooks tanpa menginstal CLI?

Hooks itu sendiri membutuhkan Claude Code CLI. Jika tujuan Anda adalah menggunakan Claude Code tanpa pengaturan lokal, jalankan di managed browser sandbox seperti Happycapy, yang menyediakan agen dan harness-nya siap pakai — ideal ketika Anda tidak ingin menginstal dan mengonfigurasi CLI sendiri.

T: Hook pertama apa yang bagus untuk ditambahkan?

Linter PostToolUse yang dicocokkan dengan Edit|Write — hook ini menjalankan formatter Anda setelah setiap perubahan kode, sehingga output agen selalu memenuhi aturan gaya penulisan Anda. Ini berisiko rendah dan langsung berguna.

Panduan terkait

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?