Claude Code 的 Notification hook：觸發時機與使用方式

01通知類型

Notification hook 的 matcher 就是通知類型。留空即對所有類型執行，或用 | 列出你要的類型。最常用的類型如下：

還有其他類型，例如 agent view 中背景工作階段使用的 agent_needs_input 和 agent_completed，以及用於等待用量限制的一系列 quota_auto_resume_* 類型。完整的最新清單請見 hooks 參考文件。

02觸發時機規則

這是最容易讓人踩雷的地方。Notification hook 和 Claude Code 本身的桌面通知共用同一套觸發時機，所以在 terminal 工作階段中，只有在你離開視線時才會觸發：

• permission_prompt 會在 prompt 出現時啟動約六秒的計時器，每次按鍵都會重新計時。如果你很快就回應，它就不會觸發。
• idle_prompt 會在 Claude 完成後約 60 秒觸發，前提是你之後都沒有輸入，且沒有背景 agent 仍在執行。Claude Code 在等待用量限制重設期間不會觸發。
• 若有其他對話框開著時又來了一個請求，計時會從請求抵達時開始算，因此即使它還排在開啟中的對話框後面，通知仍可能先送到你手上。

透過 Agent SDK 回應權限請求的宿主程式，例如 Claude Desktop 和 VS Code 擴充功能，permission_prompt 的時機不同：在請求後約六秒觸發，不會因為打字而延後，且若你或 PermissionRequest hook 先回應了就會略過。

如果想要沒有延遲的訊號，請改用其他事件：

03hook 會收到什麼

除了共通欄位（session_id、transcript_path、cwd、hook_event_name）之外，Notification hook 還會收到通知的 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 可以幫你分辨是哪個專案在發出請求。

04hook 能做與不能做的事

Notification hook 無法阻擋、延遲或修改通知。它的結束代碼和 stderr 都會被忽略，Claude Code 也會捨棄其 JSON 輸出中的 systemMessage 與 continue。它純粹用來產生副作用。

它唯一能用的輸出欄位是 terminalSequence。hook 執行時沒有 terminal，因此無法自行寫出跳脫序列，但可以交給 Claude Code 代為輸出。這讓 hook 能在 iTerm2、Ghostty、Kitty、WezTerm、Windows Terminal 等 terminal 中觸發原生通知，即使在 tmux 內也行。這只在 Claude Code 介面顯示於畫面上的互動式工作階段中有效。

preferredNotifChannel 設定也不會停用這個 hook。即使關閉內建通知，Notification 事件仍會觸發。該設定只會改變 Claude Code 本身提醒你的方式，詳見terminal 響鈴指南。

05範例

依類型使用不同處理程式

針對權限 prompt 和閒置提醒分別執行不同的腳本：

{
  "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。不在允許清單內的序列都會被忽略。

06Claude Code Notifier 的角色

呼叫 push 服務的 Notification hook 可以把提醒送到你的手機，對很多人來說這樣就夠了。ntfy 指南介紹了這種做法。

缺的是回覆。permission_prompt 觸發時，Claude 正在等待一個 Notification hook 無法回應的對話框。Claude Code Notifier 改用能回應的 hook 來處理：用 PermissionRequest 回傳你的決定，用針對 AskUserQuestion 的 PreToolUse 回傳你的答案。它的免費命令列工具 ccn 可在 Mac、Windows 和 Linux 上執行，本身就能顯示桌面通知。配對 iPhone 或 Android app 後，你可以在手機上選擇允許一次、在此工作階段中允許，或拒絕。如果你在過去 30 秒內有輸入，就不會等待手機，terminal 會照常詢問。這是獨立工具，並非 Anthropic 出品。安裝方式請見 ccn 頁面。

07常見問題