Notification Hooks

When Claude finishes working and is waiting for your input, it fires a notification event (e.g. "Claude Code — 1:emacs .config — Task completed").

For macOS/Linux, both Kitty and Ghostty natively support notification events without configuration.
iTerm2 for Mac requires a bit of configuration in its settings.
For Windows and WSL2 you will need to rely on Notification Hooks.

Notification event data format sent to hooks:

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

You can add custom logic to notification hooks. Useful on non-Linux systems where there is no native notification integration with their terminals, especially WSL2.

Notification hook has four trigger types:

permission_prompt — Claude wants to run something and needs your approval.
idle_prompt — Claude finished and is waiting for your next message.
elicitation_dialog — Claude needs clarification before it can continue.
auth_success — authentication completed successfully.

Example config (settings.json), also showing a Stop hook running PowerShell:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "powershell.exe -NoProfile -NonInteractive -Command...." }] }],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "powershell.exe -NoProfile -NonInteractive -Command...." }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "New-BurntToastNotification -Text 'Claude Code', 'Task complete'" }]
      }
    ]
  }
}

Related: Hooks, Hooks Settings