├── .gitignore ├── CLAUDE.md ├── claude-code-notifier.sh └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .claude/ -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md 2 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 | 5 | ## Project Overview 6 | 7 | This is a Claude Code notification system that provides cross-platform system notifications for Claude Code events. The project consists of a shell script (`claude-code-notifier.sh`) that integrates with Claude Code hooks to display notifications when various events occur. 8 | 9 | ## Key Components 10 | 11 | - **claude-code-notifier.sh**: Main notification script that handles cross-platform notification display 12 | - Supports macOS (via terminal-notifier), Linux (via notify-send), and Windows (via PowerShell toast notifications) 13 | - Processes JSON input from Claude Code hooks 14 | - Customizes notification messages based on event types (SessionStart, SessionEnd, Stop, Notification) 15 | 16 | ## Dependencies 17 | 18 | ### macOS 19 | - `terminal-notifier`: Install via `brew install terminal-notifier` 20 | - `jq`: Install via `brew install jq` 21 | 22 | ### Linux 23 | - `notify-send`: Usually pre-installed, install via `sudo apt install libnotify-bin` if missing 24 | 25 | ### Windows 26 | - PowerShell (built-in on modern Windows) 27 | 28 | ## Configuration 29 | 30 | The script is designed to be placed in `~/.claude/claude-code-notifier.sh` and configured in Claude Code's `~/.claude/settings.json` with hooks for: 31 | - SessionStart 32 | - SessionEnd 33 | - Stop 34 | - Notification 35 | 36 | ## Testing 37 | 38 | To test the notification script manually: 39 | ```bash 40 | echo '{"message":"Test notification","hook_event_name":"Notification"}' | ./claude-code-notifier.sh 41 | ``` 42 | 43 | ## Architecture 44 | 45 | The script follows a simple event-driven architecture: 46 | 1. Reads JSON input from stdin containing message and hook event data 47 | 2. Processes the event type to customize the notification message 48 | 3. Detects the operating system and uses the appropriate notification system 49 | 4. Falls back to terminal echo if no notification system is available 50 | 51 | The script is platform-agnostic and handles OS detection automatically, making it suitable for cross-platform deployment. -------------------------------------------------------------------------------- /claude-code-notifier.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | #============================================================================== 4 | # Claude Code Notification Hook Script 5 | # This script displays system notifications when Claude Code triggers hooks 6 | #============================================================================== 7 | 8 | # Read JSON input from stdin 9 | input=$(cat) 10 | 11 | # Extract message and event from JSON input 12 | message=$(echo "$input" | jq -r '.message // "Claude Code Notification"') 13 | hook_event=$(echo "$input" | jq -r '.hook_event_name // "Unknown"') 14 | 15 | # Fallback if jq is not available 16 | if [ $? -ne 0 ] || [ "$message" = "null" ]; then 17 | message="Claude Code Notification" 18 | fi 19 | 20 | #============================================================================== 21 | # Customize message based on event type 22 | #============================================================================== 23 | case "$hook_event" in 24 | "SessionStart") 25 | message="Session started 🚀" 26 | ;; 27 | "SessionEnd") 28 | message="Session completed ✅" 29 | ;; 30 | "Stop") 31 | message="Response finished 🏁" 32 | ;; 33 | "Notification") 34 | # Keep the original message from Claude 35 | ;; 36 | *) 37 | message="$hook_event: $message" 38 | ;; 39 | esac 40 | 41 | #============================================================================== 42 | # Detect operating system and show notification accordingly 43 | #============================================================================== 44 | case "$(uname -s)" in 45 | Darwin*) 46 | # macOS - use terminal-notifier 47 | terminal-notifier -title "Claude Code" -message "$message" -sound default 48 | ;; 49 | 50 | Linux*) 51 | # Linux - use notify-send 52 | if command -v notify-send >/dev/null 2>&1; then 53 | notify-send "Claude Code" "$message" -i dialog-information 54 | else 55 | echo "notify-send not found. Install libnotify-bin package." 56 | echo "Claude Code: $message" 57 | fi 58 | ;; 59 | 60 | CYGWIN*|MINGW*|MSYS*) 61 | # Windows - use PowerShell toast notification 62 | powershell.exe -Command " 63 | [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null; 64 | [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null; 65 | \$template = @' 66 | 67 | 68 | 69 | Claude Code 70 | $message 71 | 72 | 73 | 74 | '@; 75 | \$xml = New-Object Windows.Data.Xml.Dom.XmlDocument; 76 | \$xml.LoadXml(\$template); 77 | \$toast = [Windows.UI.Notifications.ToastNotification]::new(\$xml); 78 | [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show(\$toast);" 79 | ;; 80 | 81 | *) 82 | # Fallback - just echo to terminal 83 | echo "Claude Code Notification: $message" 84 | ;; 85 | esac 86 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Claude Code Notification 2 | 3 | 📢 Send system notifications when Claude Code requests permissions or completes tasks 4 | 5 | A cross-platform notification script that integrates with Claude Code to show system notifications for various events like session completions and permission requests. 6 | 7 | ## Installation 8 | 9 | ### Step 1: Install terminal-notifier (macOS only) 10 | ```bash 11 | brew install terminal-notifier 12 | ``` 13 | 14 | ### Step 2: Create the script file 15 | ```bash 16 | curl -o ~/.claude/claude-code-notifier.sh https://raw.githubusercontent.com/hta218/claude-code-notifier/main/claude-code-notifier.sh 17 | ``` 18 | 19 | ### Step 3: Make it executable (macOS/Linux) 20 | ```bash 21 | chmod +x ~/.claude/claude-code-notifier.sh 22 | ``` 23 | **Note**: Windows users can skip this step. 24 | 25 | ### Step 4: Enable notifications on your system 26 | Make sure notifications are enabled for Terminal/your shell application in your system settings. 27 | 28 | ![Enable Terminal Notifications](https://cdn.shopify.com/s/files/1/0669/0262/2504/files/terminal-notifier.png?v=1756888696) 29 | 30 | ### Step 5: Add configuration to Claude settings 31 | Create or edit `~/.claude/settings.json` and add: 32 | ```json 33 | { 34 | "hooks": { 35 | "Notification": [ 36 | { 37 | "hooks": [ 38 | { 39 | "type": "command", 40 | "command": "~/.claude/claude-code-notifier.sh" 41 | } 42 | ] 43 | } 44 | ], 45 | "Stop": [ 46 | { 47 | "hooks": [ 48 | { 49 | "type": "command", 50 | "command": "~/.claude/claude-code-notifier.sh" 51 | } 52 | ] 53 | } 54 | ], 55 | "SessionEnd": [ 56 | { 57 | "hooks": [ 58 | { 59 | "type": "command", 60 | "command": "~/.claude/claude-code-notifier.sh" 61 | } 62 | ] 63 | } 64 | ], 65 | "SessionStart": [ 66 | { 67 | "hooks": [ 68 | { 69 | "type": "command", 70 | "command": "~/.claude/claude-code-notifier.sh" 71 | } 72 | ] 73 | } 74 | ] 75 | } 76 | } 77 | ``` 78 | 79 | ### Step 6: Restart Claude Code 80 | Restart Claude Code to apply the changes then simply prompt 'Hello' to see notifications in action. 81 | 82 | ## Usage 83 | 84 | Once installed, the script will automatically trigger notifications with default System sounds when Claude Code: 85 | - Starts sessions (SessionStart hook) 86 | - Requests permissions or user input (Notification hook) 87 | - Completes tasks or responses (Stop hook) 88 | - Ends sessions (SessionEnd hook) 89 | 90 | ![Notification Preview](https://cdn.shopify.com/s/files/1/0669/0262/2504/files/terminal-notifier-noties.png?v=1756889242) 91 | 92 | ## Event Types 93 | 94 | The script handles different notification types: 95 | 96 | - **SessionStart**: Shows "Session started 🚀" 97 | - **SessionEnd**: Shows "Session completed ✅" 98 | - **Stop**: Shows "Response finished 🏁" 99 | - **Notification**: Shows the original message from Claude 100 | - **Other events**: Shows the event name with the message 101 | 102 | ## Requirements 103 | 104 | ### macOS (recommended) 105 | - [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) for pushing notifications 106 | - [`jq`](https://github.com/jqlang/jq) for JSON processing 107 | - Install: `brew install terminal-notifier jq` 108 | 109 | ### Linux 110 | - `notify-send` (usually pre-installed) 111 | - Install if missing: `sudo apt install libnotify-bin` 112 | 113 | ### Windows 114 | - PowerShell (built-in on modern Windows) 115 | - Uses Windows Toast notifications 116 | 117 | ## Customization 118 | 119 | You can modify the script to: 120 | - Change notification messages 121 | - Add different sounds 122 | - Log notifications to a file (uncomment the last line) 123 | - Customize notification appearance 124 | 125 | ## Contributing 126 | 127 | Feel free to submit issues and pull requests to improve the script! 128 | --------------------------------------------------------------------------------