Claude Code macOS Notifications Setup - Automated installation guide for system notifications with sound

README.md

Claude Code macOS Notifications Setup

This document provides instructions for Claude Code to automatically set up macOS system notifications for when Claude is waiting for user input or has completed tasks.

What This Sets Up

• System notifications when Claude needs permission for tools
• System notifications when Claude has been idle waiting for input
• Sound alerts (Glass sound) with each notification
• Notification logging for debugging

User Prompt for Setup

The user should enter this prompt to Claude Code:

Please follow the instructions in: https://gist.github.com/TristanBrotherton/90c80b6a90791f020a0877aa5202b7c0

Installation Instructions for Claude Code

When a user requests Claude Code notification setup, follow these steps:

1. Check Prerequisites and Install Dependencies

First, check if terminal-notifier is installed and install if needed:

# Check if terminal-notifier exists
brew list | grep terminal-notifier || echo "terminal-notifier not installed"

# Install if missing
brew install terminal-notifier

2. Verify System Requirements

Check essential requirements:

# Verify Glass sound file exists
ls -la /System/Library/Sounds/Glass.aiff

# Check if Claude settings directory exists, create if needed
mkdir -p ~/.claude

# Get username for path resolution
echo "Username: $(whoami)"

3. Create the Notification Hook Script

Create the notification hook script at ~/.claude/notification-hook.sh:

#!/bin/bash

# Claude Code macOS Notification Hook
# Reads JSON from stdin and sends macOS notification

# Read the JSON input from stdin
json_input=$(cat)

# Extract the message using simple pattern matching
# (Using sed for compatibility, could use jq if available)
message=$(echo "$json_input" | sed -n 's/.*"message"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')

# Clean up any escaped characters
message=$(echo "$message" | sed 's/\\!/!/g' | sed 's/\\"/"/g')

# Send macOS notification using terminal-notifier if available, otherwise osascript
if [ -n "$message" ]; then
    # Try terminal-notifier first (if installed via homebrew)
    if command -v terminal-notifier &> /dev/null; then
        terminal-notifier -title "Claude Code" -message "$message" -sound Glass
        # Also play sound separately to ensure it's heard
        afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
    else
        # Fallback to osascript with both notification and sound
        osascript <<EOF
display notification "$message" with title "Claude Code" sound name "Glass"
EOF
        # Also play sound separately to ensure it's heard
        afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
    fi
fi

# Log for debugging (optional - remove if not needed)
echo "$(date): $message" >> ~/.claude/notification.log

Make the script executable:

chmod +x ~/.claude/notification-hook.sh

4. Update Claude Settings

IMPORTANT: Backup existing settings first if they exist:

# Backup existing settings if they exist
if [ -f ~/.claude/settings.json ]; then
    cp ~/.claude/settings.json ~/.claude/settings.json.backup
fi

Read the current settings and determine the approach:

• If ~/.claude/settings.json doesn't exist, create it with the notification hook
• If it exists, read it and add the hooks section to the existing JSON structure

Use the actual username (from $USER or whoami) in the path, not a placeholder.

Example new settings.json:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/USERNAME/.claude/notification-hook.sh"
          }
        ]
      }
    ]
  }
}

Example adding to existing settings:

{
  "statusLine": {
    "type": "command",
    "command": "existing command here"
  },
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/USERNAME/.claude/notification-hook.sh"
          }
        ]
      }
    ]
  }
}

5. Test the Setup

Test the notification system with this command:

echo '{"message": "Claude Code notifications are working!", "hook_event_name": "Notification"}' | ~/.claude/notification-hook.sh

The user should:

• See a macOS notification with "Claude Code" title
• Hear the Glass sound
• See a log entry in ~/.claude/notification.log

6. Verify Notification Permissions

If notifications don't appear, guide the user to check:

1. System Preferences > Notifications & Focus > Terminal

   • Ensure "Allow Notifications" is enabled
   • Set alert style to "Alerts" or "Banners"
   • Enable sound if desired

2. Test system volume and sound:

   afplay /System/Library/Sounds/Glass.aiff

Usage

Once installed, notifications will automatically appear when:

• Claude needs permission to use a tool not in the allow list
• Claude has been idle waiting for user input

Troubleshooting

No notifications appearing:

• Check Terminal notification permissions in System Preferences
• Verify the script path in settings.json matches the actual file location
• Test with the manual command above

No sound:

• Check system volume and mute status
• Verify Glass.aiff exists: ls /System/Library/Sounds/Glass.aiff
• Test sound manually: afplay /System/Library/Sounds/Glass.aiff

Script not found errors:

• Verify script exists and is executable: ls -la ~/.claude/notification-hook.sh
• Check the username in the settings.json path matches actual user

JSON syntax errors:

• Validate settings.json syntax with: python -m json.tool ~/.claude/settings.json
• Restore from backup if needed: cp ~/.claude/settings.json.backup ~/.claude/settings.json

Files Created/Modified

• ~/.claude/notification-hook.sh - The notification script
• ~/.claude/settings.json - Updated Claude settings (backed up first)
• ~/.claude/settings.json.backup - Backup of original settings (if existed)
• ~/.claude/notification.log - Log file for debugging notifications