Notification hook w Claude Code: kiedy się uruchamia i jak go używać

01Typy powiadomień

matcher w hooku Notification to typ powiadomienia. Zostaw go pustego, żeby działał dla wszystkich, albo wypisz te, które chcesz, rozdzielając je |. Typy, których najpewniej użyjesz:

Jest ich więcej, np. agent_needs_input i agent_completed dla sesji w tle w widoku agentów oraz zestaw typów quota_auto_resume_* przy czekaniu na limit użycia. Pełną, aktualną listę znajdziesz w dokumentacji hooków.

02Zasady timingu

Tu właśnie wiele osób się potyka. Hook Notification działa w tym samym rytmie co wbudowane powiadomienia desktopowe Claude Code, więc w sesji w terminalu odpala się tylko wtedy, gdy odwrócisz wzrok:

• permission_prompt uruchamia licznik ok. sześciu sekund, gdy pojawi się prompt. Każde naciśnięcie klawisza go resetuje. Jeśli odpowiesz szybko, hook w ogóle się nie odpali.
• idle_prompt odpala się ok. 60 sekund po tym, jak Claude skończy, ale tylko jeśli od tego czasu nic nie wpisałeś i żaden agent w tle już nie działa. Nie odpala się, gdy Claude Code czeka na reset limitu użycia.
• Żądanie, które przyjdzie, gdy otwarte jest inne okno dialogowe, jest liczone od momentu nadejścia, więc powiadomienie może do ciebie dotrzeć, zanim jeszcze to żądanie wyjdzie z kolejki za otwartym oknem.

Hosty, które obsługują uprawnienia przez Agent SDK, np. Claude Desktop i rozszerzenie VS Code, liczą czas permission_prompt inaczej: ok. sześć sekund od żądania, bez odraczania przez pisanie, i pomijają powiadomienie, jeśli ty albo hook PermissionRequest odpowiecie wcześniej.

Jeśli chcesz sygnału bez opóźnienia, użyj innego zdarzenia:

03Co dostaje hook

Oprócz wspólnych pól (session_id, transcript_path, cwd, hook_event_name) hook Notification dostaje message powiadomienia, opcjonalny title oraz notification_type:

{
  "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 to tekst samego Claude Code, więc możesz go spokojnie wyświetlić bez zmian. cwd przydaje się, gdy masz kilka sesji i chcesz wiedzieć, który projekt pyta.

04Co hook może, a czego nie

Hook Notification nie może zablokować, opóźnić ani zmienić powiadomienia. Jego exit code i stderr są ignorowane, a Claude Code odrzuca systemMessage i continue z jego wyjścia JSON. Służy wyłącznie do efektów ubocznych.

Jest jedno pole wyjściowe, którego może użyć: terminalSequence. Hooki działają bez terminala, więc same nie mogą wypisać sekwencji escape, ale mogą przekazać ją Claude Code do wyemitowania. Dzięki temu hook może wywołać natywne powiadomienie terminala w iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal i innych, nawet wewnątrz tmux. Działa to tylko w sesji interaktywnej, gdy interfejs Claude Code jest na ekranie.

Ustawienie preferredNotifChannel też nie wyłącza hooka. Nawet przy wyłączonych wbudowanych powiadomieniach zdarzenie Notification nadal się odpala. To ustawienie zmienia tylko sposób, w jaki Claude Code sam cię powiadamia; zobacz poradnik o dzwonku terminala.

05Przykłady

Osobne handlery dla każdego typu

Uruchamiaj osobny skrypt dla promptów o uprawnienia i dla przypomnień o bezczynności:

{
  "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" }]
      }
    ]
  }
}

Nadaj każdemu skryptowi prawa wykonywania przez chmod +x. Komendy do powiadomień desktopowych na Maca, Windows i Linux znajdziesz w poradniku jak dostać powiadomienie, gdy Claude Code skończy, więc nie powtarzamy ich tutaj.

Pokaż prawdziwą wiadomość i projekt

Ten skrypt (macOS i Linux) wstawia do powiadomienia wiadomość Claude Code i folder projektu zamiast stałego tekstu:

#!/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

Przekazywanie tekstu jako argumentów (on run argv) sprawia, że AppleScript się nie wysypie, gdy wiadomość zawiera cudzysłowy. Wymaga zainstalowanego jq.

Natywne powiadomienie terminala

Przykład od Anthropic używa terminalSequence z OSC 777, które rozumieją Ghostty, Warp i urxvt:

#!/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}'

W iTerm2, Windows Terminal czy WezTerm użyj zamiast tego OSC 9, a w Kitty OSC 99. Wszystko spoza dozwolonych sekwencji jest ignorowane.

06Gdzie pasuje Claude Code Notifier

Hook Notification, który wywołuje usługę push, dostarczy alert na telefon i dla wielu osób to wystarczy. Tę drogę opisuje poradnik o ntfy.

Brakuje tylko odpowiedzi. Gdy permission_prompt się odpala, Claude czeka na okno dialogowe, na które hook Notification nie odpowie. Claude Code Notifier rozwiązuje to hookami, które to potrafią: PermissionRequest zwraca twoją decyzję, a PreToolUse na AskUserQuestion twoją odpowiedź. Jego darmowe narzędzie CLI, ccn, działa na Macu, Windows i Linux i samo pokazuje powiadomienia desktopowe. Po sparowaniu aplikacji na iPhone lub Android możesz z telefonu zezwolić raz, zezwolić na całą sesję albo odmówić. Jeśli pisałeś w ciągu ostatnich 30 sekund, nic nie czeka na telefon i terminal pyta jak zwykle. To niezależne narzędzie, niestworzone przez Anthropic. Instrukcję instalacji znajdziesz na stronie ccn.

07FAQ