Desktop Notification Hook

Hook Type

Notification -- Fires when Claude Code needs user attention (permission requests, questions, task completion).

Description

This hook sends a native OS desktop notification so you can context-switch away from the terminal and still be alerted when Claude needs input. Supports macOS and Linux out of the box.

Patterns/Rules

• Triggers on all notification events (empty matcher = match everything)
• Uses osascript on macOS for native Notification Center integration
• Uses notify-send on Linux for freedesktop notifications
• Zero dependencies on macOS; requires libnotify on Linux

Configuration

macOS

Copy
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\" sound name \"Ping\"'"
          }
        ]
      }
    ]
  }
}

Linux

Copy
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention' --urgency=normal --icon=terminal"
          }
        ]
      }
    ]
  }
}

Cross-Platform (auto-detect)

Copy
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "if [ \"$(uname)\" = \"Darwin\" ]; then osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\" sound name \"Ping\"'; else notify-send 'Claude Code' 'Claude Code needs your attention' --urgency=normal 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

Action

When the Notification event fires, the hook executes the OS-specific notification command. The notification appears in your system tray / notification center with the title "Claude Code".