Claude Code Notification hook: ne zaman tetiklenir ve nasıl kullanılır

01Bildirim türleri

Bir Notification hook'undaki matcher, bildirim türüdür. Hepsinde çalışması için boş bırakın ya da istediklerinizi | ile listeleyin. En çok kullanacağınız türler:

Başka türler de var: agent view'daki arka plan oturumları için agent_needs_input ve agent_completed, kullanım limiti beklemeleri için de bir dizi quota_auto_resume_* türü. Tam ve güncel liste hook referansında.

02Zamanlama kuralları

İnsanların en çok takıldığı nokta burası. Notification hook'u, Claude Code'un kendi masaüstü bildirimleriyle aynı zamanlamayı kullanır; bu yüzden bir terminal oturumunda yalnızca ekrandan uzaklaştığınızda tetiklenir:

• permission_prompt, prompt göründüğünde yaklaşık altı saniyelik bir zamanlayıcı başlatır. Her tuş vuruşu bu zamanlayıcıyı sıfırlar. Hızlı yanıt verirseniz hiç tetiklenmez.
• idle_prompt, Claude işini bitirdikten yaklaşık 60 saniye sonra tetiklenir; ancak bu süre içinde hiçbir şey yazmadıysanız ve çalışan bir arka plan ajanı yoksa. Claude Code bir kullanım limitinin sıfırlanmasını beklerken tetiklenmez.
• Başka bir iletişim kutusu açıkken gelen bir istek, geldiği andan itibaren zamanlanır; bu nedenle istek hâlâ açık iletişim kutusunun arkasında beklerken bildirimi size ulaşabilir.

İzinleri Agent SDK üzerinden yanıtlayan Claude Desktop ve VS Code eklentisi gibi ortamlar permission_prompt'u farklı zamanlar: istekten yaklaşık altı saniye sonra tetiklenir, yazmanız onu ertelemez ve siz ya da bir PermissionRequest hook'u önce yanıt verirse atlanır.

Gecikmesiz bir sinyal istiyorsanız başka bir event kullanın:

03Hook'un aldığı veriler

Ortak alanlara (session_id, transcript_path, cwd, hook_event_name) ek olarak bir Notification hook'u bildirimin message alanını, isteğe bağlı bir title ve notification_type alanını alır:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

message, Claude Code'un kendi ifadesidir; dolayısıyla olduğu gibi göstermek güvenlidir. Birden fazla oturum çalıştırıyorsanız ve hangi projenin sorduğunu bilmek istiyorsanız cwd işinize yarar.

04Hook'un yapabildikleri ve yapamadıkları

Bir Notification hook'u bildirimi engelleyemez, geciktiremez veya değiştiremez. Çıkış kodu ve stderr yok sayılır; Claude Code JSON çıktısındaki systemMessage ve continue alanlarını da göz ardı eder. Tamamen yan etkiler içindir.

Kullanabileceği tek bir çıktı alanı var: terminalSequence. Hook'lar terminal olmadan çalıştığı için escape dizilerini kendileri yazamaz, ancak Claude Code'a yazdırması için bir dizi iletebilir. Bu sayede bir hook; iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal ve diğerlerinde, hatta tmux içinde bile terminalin kendi bildirimini tetikleyebilir. Bu yalnızca Claude Code arayüzünün ekranda olduğu etkileşimli bir oturumda çalışır.

preferredNotifChannel ayarı da hook'u durdurmaz. Yerleşik bildirimler kapalıyken bile Notification event'i tetiklenmeye devam eder. Bu ayar yalnızca Claude Code'un sizi nasıl uyardığını değiştirir; ayrıntılar için terminal zili rehberine bakın.

05Örnekler

Türe göre farklı handler'lar

İzin prompt'ları ve boşta kalma hatırlatmaları için ayrı script'ler çalıştırın:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-alert.sh" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/idle-alert.sh" }]
      }
    ]
  }
}

Her script'i chmod +x ile çalıştırılabilir yapın. Mac, Windows ve Linux için masaüstü bildirim komutları Claude Code bitirdiğinde nasıl bildirim alınır rehberinde yer aldığından burada tekrarlanmıyor.

Gerçek mesajı ve projeyi gösterin

Bu script (macOS ve Linux), sabit bir metin yerine Claude Code'un mesajını ve proje klasörünü bildirime ekler:

#!/bin/bash
# ~/.claude/hooks/notify.sh
input=$(cat)
msg=$(jq -r '.message // "Claude Code needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // "."' <<<"$input")")

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'on run argv' \
            -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
            -e 'end run' "$msg" "Claude Code: $project"
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code: $project" "$msg"
fi
exit 0

Metni argüman olarak geçirmek (on run argv), mesaj tırnak işareti içerdiğinde AppleScript'in bozulmasını önler. jq kurulu olmalıdır.

Terminalin kendi bildirimi

Anthropic'in kendi örneği, Ghostty, Warp ve urxvt'nin anladığı OSC 777 ile terminalSequence kullanır:

#!/bin/bash
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

iTerm2, Windows Terminal veya WezTerm için bunun yerine OSC 9, Kitty için ise OSC 99 kullanın. İzin verilen diziler dışındaki her şey yok sayılır.

06Claude Code Notifier'ın yeri

Bir push servisini çağıran Notification hook'u uyarıyı telefonunuza ulaştırır ve çoğu kişi için bu yeterlidir. Bu yöntemi ntfy rehberi anlatıyor.

Eksik kalan kısım yanıt vermek. permission_prompt tetiklendiğinde Claude, bir Notification hook'unun yanıtlayamayacağı bir iletişim kutusunda bekliyor olur. Claude Code Notifier bunu yanıt verebilen hook'larla çözer: kararınızı döndürmek için PermissionRequest, cevabınızı döndürmek için ise AskUserQuestion üzerinde PreToolUse. Ücretsiz komut satırı aracı ccn, Mac, Windows ve Linux üzerinde çalışır ve tek başına masaüstü bildirimleri gösterir. iPhone veya Android uygulamasını eşleştirdiğinizde telefondan bir kez izin verebilir, oturum boyunca izin verebilir ya da reddedebilirsiniz. Son 30 saniye içinde bir şey yazdıysanız telefon beklenmez ve terminal her zamanki gibi sorar. Bağımsız bir araçtır ve Anthropic tarafından geliştirilmemiştir. Kurulum bilgileri ccn sayfasında.

07SSS