claude-code-ntfy-notification-hook

A Claude Code hook that forwards Notification events to an ntfy.sh topic as push notifications.

Installation

pip install claude-code-ntfy-notification-hook

Usage

Configure Claude Code to call send-ntfy-claude-notification as a hook for Notification events. In your Claude Code settings (.claude/settings.json or ~/.claude/settings.json):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "send-ntfy-claude-notification my-ntfy-topic"
          }
        ]
      }
    ]
  }
}

Replace my-ntfy-topic with your ntfy.sh topic name.

Configuration

A YAML configuration file can be placed at $XDG_CONFIG_HOME/send-ntfy-claude-notification/config.yaml (typically ~/.config/send-ntfy-claude-notification/config.yaml):

topic: my-ntfy-topic        # Default topic (overridden by CLI argument)
server: https://ntfy.sh     # ntfy.sh server URL
priority: 3                 # 1 (min) – 5 (urgent)
icon: https://upload.wikimedia.org/wikipedia/commons/thumb/b/b0/Claude_AI_symbol.svg/250px-Claude_AI_symbol.svg.png
log_level: WARNING          # DEBUG / INFO / WARNING / ERROR / CRITICAL
log_file: ""                # Leave empty to log to stdout

Notification type emoji mapping

Command-line reference

usage: send-ntfy-claude-notification [-h] [--server SERVER] [--priority {1-5}]
                                     [--icon ICON] [--log-file PATH]
                                     [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                                     [-v]
                                     [topic]

positional arguments:
  topic                 ntfy.sh topic name (required if not set in config)

options:
  --server SERVER       ntfy.sh server base URL (default: https://ntfy.sh)
  --priority {1-5}      Notification priority 1 (min) – 5 (urgent) (default: 3)
  --icon ICON           Icon URL attached to the notification
  --log-file PATH       Write logs to this file instead of stdout
  --log-level ...       Minimum log level (default: WARNING)
  -v, --verbose         Enable verbose output (overrides --log-level to DEBUG)

License

GPL-3.0-or-later