claude-code-notify

Claude Code Notify

Get desktop notifications when Claude Code requests tool execution permission or completes tasks.

Features

• 🔔 Simple desktop notifications for Claude Code interactions
• 🎵 Different notification sounds (Ping for tool requests, Glass for completions)
• 🍎 Native macOS integration

Getting Started

1. Run the Tool

No installation required! Use directly with npx:

npx claude-code-notify

This automatically downloads and runs the latest version from npm.

2. Enable Notification Permissions

• Open System Settings → Notifications
• Find and select Script Editor from the list
• Ensure "Allow Notifications" is checked
• Configure notification style (Banner or Alert)
• Test with: osascript -e "display notification \"Test\" with title \"Test\""

3. Configure Claude Code Hook

• In Claude Code, run the /hooks command
• Select Notification from the list
• Choose Add new hook
• Enter npx claude-code-notify as the command
• Save the configuration

This setup ensures you always use the latest version without manual installation.

The resulting configuration in ~/.claude/settings.json will look like:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-code-notify"
          }
        ]
      }
    ]
  }
}

For more details about hooks, see: https://docs.anthropic.com/en/docs/claude-code/hooks

Notification Types

The script provides simple, clear notifications:

• Tool Execution Requests: When Claude asks for permission to execute commands

  • Sound: Ping
  • Message: "🔧 Tool execution pending"

• Task Completion: When Claude completes a response

  • Sound: Glass
  • Message: "✅ Response completed"

Requirements

• macOS (uses osascript for notifications)
• Claude Code with hooks functionality
• Bash shell

How It Works

• Claude Code executes the notification script via hooks
• Script finds the latest conversation file in ~/.claude/projects
• Determines notification type based on message content
• Displays native macOS notification with appropriate sound

License

MIT