Claude Code hook'ları: tüm olaylar ve ne işe yaradıkları

01Bir hook nasıl yapılandırılır

Bir hook yapılandırması üç seviyeden oluşur:

1. PreToolUse veya Stop gibi bir hook olayı.
2. Ne zaman tetikleneceğini filtreleyen bir matcher grubu; örneğin "yalnızca Bash aracı için".
3. Asıl çalışan kısım olan bir veya daha fazla hook handler.

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

Bu örnek, Claude bir dosya yazdıktan veya düzenledikten sonra bir lint script'i çalıştırır. İkinci bir olay eklemek için aynı hooks nesnesinin içine yeni bir anahtar ekleyin.

02Hook'lar nerede tanımlanır

Farklı dosyalardaki hook'lar birbirinin yerini almaz, birleşir. Tüm etkin hook'ları ve nereden geldiklerini görmek için Claude Code'da /hooks yazın.

Etkileşimli bir oturumda Claude Code, klasör için çalışma alanı güven iletişim kutusunu onaylayana kadar hook'ları, kendi hook'larınız dahil, çalıştırmaz.

03Handler türleri

Çoğu hook, bir shell komutu çalıştıran "type": "command" türündedir. Diğer dört tür şunlardır:

• http: Olay JSON'unu bir URL'ye POST eder ve yanıt gövdesini okur.
• mcp_tool: Yapılandırdığınız bir MCP sunucusundaki bir aracı çağırır.
• prompt: Bir Claude modeline tek seferlik bir soru sorar ve JSON formatında bir karar okur.
• agent: Karar vermeden önce dosyaları okuyabilen bir subagent başlatır (deneysel).

Command hook'ları tam kullanıcı izinlerinizle çalışır: macOS ve Linux'ta sh -c üzerinden, Windows'ta ise Git Bash (veya PowerShell) üzerinden. Bir hook'u arka planda çalıştırmak için "async": true ekleyin; ancak bu durumda artık karar veremez.

04Matcher'lar

matcher, bir olayın hangi durumlarda hook'u çalıştıracağını belirler. Neyle eşleştirileceği olaya bağlıdır: araç olaylarında araç adı, Notification için bildirim türü, SessionStart için oturumun nasıl başladığı vb.

• "*", "" veya hiç matcher olmaması her şeyle eşleşir.
• Harfler, rakamlar, _, -, boşluklar, | ve , tam ad olarak değerlendirilir. Edit|Write her iki araçla da eşleşir.
• Diğer her şey JavaScript regular expression'ı olarak yorumlanır; örneğin mcp__memory__.* tek bir MCP sunucusundaki tüm araçlarla eşleşir.

Matcher'lar büyük/küçük harfe duyarlıdır. Stop ve UserPromptSubmit gibi bazı olaylar matcher'ları yok sayar. Araç olaylarında, "Bash(git *)" gibi bir izin kuralı içeren if alanı tek bir handler'ı daha da daraltır.

05Girdi: hook'unuza ne gelir

Her hook, stdin üzerinden session_id, transcript_path, cwd ve hook_event_name gibi ortak alanların yanı sıra olaya özgü alanlar içeren bir JSON alır. Örneğin bir Bash çağrısı için çalışan PreToolUse hook'u ayrıca tool_name ve tool_input.command alanlarını da alır. Bu veriyi jq veya herhangi bir JSON parser ile okuyabilirsiniz:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Çıktı: çıkış kodları ve JSON

Bir hook iki yoldan biriyle yanıt verir.

Çıkış kodları. 0 başarı demektir. 2 engelleyici bir hatadır: engelleme yapabilen event'lerde işlem durur ve stderr çıktınız gerekçe olarak kullanılır. Alışılmış 1 dahil diğer tüm kodlar engelleyici olmayan hatadır; işlem devam eder ve bir hook hatası bildirimi görürsünüz. Hook bir kuralı zorunlu kılmak için yazıldıysa 1 ile değil, 2 ile çıkın.

stdout'a JSON. Daha ince kontrol için 0 ile çıkın ve tek bir JSON nesnesi yazdırın. Bazı alanlar her yerde çalışır; örneğin Claude'u tamamen durdurmak için continue: false. Diğerleri event'e özeldir: Stop, bir reason ile birlikte decision: "block" kullanırken PreToolUse ve PermissionRequest kararlarını hookSpecificOutput içine koyar. stdout'a başka hiçbir şey yazdırmayın: shell profilinizden gelen tek bir fazla satır bile Claude Code'un JSON'u okumasını engeller.

07Tüm hook event'leri

Anthropic zaman zaman yeni event'ler ekliyor; güncel liste ve her event'in girdi alanları için hook referansına göz atın.

08Bildirimler için hangi event'ler önemli

İnsanların haberdar olmak istediği neredeyse her şeyi dört event karşılar:

• "Claude işini bitirdi" için Stop. Stop hook rehberine bakın.
• "Claude sizi bekliyor" için permission_prompt ve idle_prompt gibi türleriyle Notification. Notification hook rehberine bakın.
• Bir izin gerektiği anda haberdar olmak ya da yanıt vermek için PermissionRequest. PermissionRequest rehberine bakın.
• Claude'un çoktan seçmeli sorularını görmek veya yanıtlamak için AskUserQuestion aracında PreToolUse. Soruları telefondan yanıtlama rehberine bakın.

Doğrudan yapıştırılabilir bir masaüstü kurulumu için Claude Code bittiğinde nasıl bildirim alınır rehberiyle başlayın.

09Claude Code Notifier'ın yeri

Claude Code Notifier tamamen bu hook'lar üzerine kuruludur. Ücretsiz komut satırı aracı ccn; Mac, Windows ve Linux'ta çalışır. Kurulduğunda ~/.claude/settings.json dosyasına her biri ccn hook çalıştıran yedi hook girdisi ekler ve dosyanın tek seferlik bir yedeğini alır. ccn her event için birkaç milisaniye çalışıp kapanır, yani arka planda çalışır durumda hiçbir şey kalmaz.

Tek başına masaüstü bildirimleri gösterir. iPhone veya Android uygulaması eşleştirildiğinde aynı hook'lar yanıtlarınızı geri taşır: bir izne onay verebilir ya da reddedebilir, bir soruyu yanıtlayabilir veya Claude durduktan sonra sonraki talimatı gönderebilirsiniz. Bağımsız bir araçtır, Anthropic tarafından yapılmamıştır. Yalnızca bir log ya da lint adımına ihtiyacınız varsa kendi yazacağınız birkaç satır daha basittir. Ayrıntılar ccn sayfasında.

10SSS