ה-Notification hook של Claude Code: מתי הוא מופעל ואיך משתמשים בו

01סוגי ההתראות

ה-matcher ב-hook מסוג Notification הוא סוג ההתראה. השאירו אותו ריק כדי להריץ על כל הסוגים, או פרטו את הסוגים הרצויים עם |. הסוגים שסביר שתשתמשו בהם:

יש סוגים נוספים, כמו agent_needs_input ו-agent_completed לסשנים ברקע בתצוגת הסוכנים, וסדרת סוגי quota_auto_resume_* להמתנות בגלל מגבלת שימוש. הרשימה המלאה והעדכנית נמצאת ב-תיעוד ה-hooks.

02כללי התזמון

זה החלק שמפיל הרבה אנשים. ל-hook Notification יש אותו תזמון כמו להתראות שולחן העבודה של Claude Code עצמו, ולכן בסשן terminal הוא מופעל רק כשלא מסתכלים על המסך:

• permission_prompt מפעיל טיימר של כשש שניות כשה-prompt מופיע. כל הקשה על מקש מאפסת אותו. אם עונים מהר, הוא לא מופעל בכלל.
• idle_prompt מופעל כ-60 שניות אחרי ש-Claude מסיים, ורק אם לא הקלדתם מאז ואין agent ברקע שעדיין רץ. הוא לא מופעל בזמן ש-Claude Code מחכה לאיפוס מגבלת השימוש.
• בקשה שמגיעה בזמן שדיאלוג אחר פתוח נמדדת מרגע הגעתה, כך שההתראה עליה עשויה להגיע אליכם עוד כשהיא ממתינה מאחורי הדיאלוג הפתוח.

סביבות שמטפלות בהרשאות דרך ה-Agent SDK, כמו Claude Desktop והתוסף ל-VS Code, מתזמנות את permission_prompt אחרת: כשש שניות אחרי הבקשה, בלי דחייה בגלל הקלדה, ובלי הפעלה בכלל אם אתם או hook מסוג PermissionRequest עניתם קודם.

אם צריך התראה בלי השהיה, השתמשו ב-event אחר:

03מה ה-hook מקבל

בנוסף לשדות המשותפים (session_id, transcript_path, cwd, hook_event_name), hook מסוג Notification מקבל את ה-message של ההתראה, title אופציונלי ואת ה-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 מנוסח על ידי Claude Code עצמו, כך שאפשר להציג אותו כמו שהוא. cwd שימושי כשמריצים כמה סשנים ורוצים לדעת איזה פרויקט מבקש.

04מה ה-hook יכול ומה לא

hook מסוג Notification לא יכול לחסום, לעכב או לשנות את ההתראה. קוד היציאה וה-stderr שלו מתעלמים מהם, ו-Claude Code משליך את systemMessage ואת continue מפלט ה-JSON שלו. הוא מיועד רק לתופעות לוואי.

יש שדה פלט אחד שהוא כן יכול להשתמש בו: terminalSequence. hooks רצים בלי terminal, ולכן לא יכולים לכתוב escape sequences בעצמם, אבל הם יכולים להעביר אחת ל-Claude Code כדי שהוא יפלוט אותה. כך hook יכול להפעיל התראה מובנית של ה-terminal ב-iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal ועוד, אפילו בתוך tmux. זה עובד רק בסשן אינטראקטיבי כשהממשק של Claude Code מוצג על המסך.

גם ההגדרה preferredNotifChannel לא עוצרת את ה-hook. גם כשההתראות המובנות כבויות, ה-event Notification עדיין מופעל. ההגדרה הזו משנה רק את האופן שבו Claude Code עצמו מתריע; ראו את המדריך ל-terminal bell.

05דוגמאות

handler שונה לכל סוג

הרצת סקריפט נפרד ל-permission prompts ולתזכורות idle:

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

הפכו כל סקריפט לבר-הרצה עם chmod +x. הפקודות להתראות שולחן עבודה ב-Mac, Windows ו-Linux מופיעות באיך לקבל התראה כש-Claude Code מסיים, ולכן לא נחזור עליהן כאן.

הצגת ההודעה האמיתית והפרויקט

הסקריפט הזה (macOS ו-Linux) מציג בהתראה את ההודעה של Claude Code ואת תיקיית הפרויקט, במקום מחרוזת קבועה:

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

העברת הטקסט כארגומנטים (on run argv) מונעת שבירה של ה-AppleScript כשההודעה מכילה מירכאות. נדרש jq מותקן.

התראה מובנית של ה-terminal

הדוגמה של Anthropic עצמה משתמשת ב-terminalSequence עם OSC 777, ש-Ghostty, Warp ו-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}'

ב-iTerm2, Windows Terminal או WezTerm השתמשו ב-OSC 9, וב-Kitty ב-OSC 99. כל רצף מחוץ לרצפים המותרים נשלל.

06איפה Claude Code Notifier נכנס לתמונה

hook מסוג Notification שקורא לשירות push מעביר את ההתראה לטלפון, ולהרבה אנשים זה מספיק. המדריך ל-ntfy מראה את הדרך הזו.

מה שחסר הוא התשובה. כש-permission_prompt מופעל, Claude כבר ממתין לדיאלוג ש-hook מסוג Notification לא יכול לענות עליו. Claude Code Notifier פותר את זה עם ה-hooks שכן יכולים: PermissionRequest להחזרת ההחלטה שלכם ו-PreToolUse על AskUserQuestion להחזרת התשובה שלכם. כלי שורת הפקודה החינמי שלו, ccn, רץ על Mac, Windows ו-Linux ומציג התראות שולחן עבודה בעצמו. כשאפליקציית ה-iPhone או ה-Android מחוברת, אפשר לאשר פעם אחת, לאשר לכל הסשן או לדחות ישירות מהטלפון. אם הקלדתם ב-30 השניות האחרונות, שום דבר לא ממתין לטלפון וה-terminal שואל כרגיל. הכלי עצמאי ולא פותח על ידי Anthropic. הוראות התקנה בעמוד של ccn.

07שאלות נפוצות