Simple Notifications Hook for Claude Code: Desktop Alerts for macOS & Linux

What is the Simple Notifications Hook?

The Simple Notifications Hook is a Claude Code automation hook that sends instant desktop notifications when Claude Code operations complete. It works seamlessly on both macOS and Linux systems, using native notification systems (osascript for macOS, notify-send for Linux) to alert you when tasks finish.

graph LR
    A[📝 Tool Execution] --> B[🪝 Simple Notifications Hook]
    B --> C[🔔 Desktop Alert]
    C --> D[✅ You Get Notified]

    style B fill:#F97316,stroke:#fff,color:#000
                    

Key Capabilities

• Instant Notifications - Get desktop alerts immediately when Claude Code operations complete
• Cross-Platform - Works on both macOS (osascript) and Linux (notify-send) systems
• PostToolUse Hook - Automatically triggers after any tool execution in Claude Code
• No Configuration Needed - Works out of the box with native system notifications
• Universal Matcher - Monitors all tools ("*" matcher) for completion
• Lightweight - Zero performance overhead, runs only after tool completion
• Non-Intrusive - Notifications appear as standard OS alerts

Installation

Install the Simple Notifications Hook using the Claude Code Templates CLI:

npx claude-code-templates@latest --hook automation/simple-notifications

Where is the hook installed?

The hook is saved in .claude/hooks/simple-notifications.json in your project directory:

your-project/
├── .claude/
│   └── hooks/
│       └── simple-notifications.json    # ← Hook installed here
├── src/
│   └── components/
├── package.json
└── README.md

How to Use the Hook

The Simple Notifications Hook activates automatically whenever Claude Code completes a tool operation. You don't need to explicitly request it - it works in the background!

# Start Claude Code
claude

# Use any tool or command - notifications happen automatically
> Read the package.json file
> Edit src/index.js and add a console.log
> Run npm test

After each operation completes, you'll receive a desktop notification showing which tool was executed.

Usage Examples

Example 1: File Operations

claude

> Read all TypeScript files in the src directory and analyze for bugs

Result: When Claude Code finishes reading files, you'll get a desktop notification: "Tool: Read completed"

Example 2: Code Editing

claude

> Update the authentication logic in src/auth.ts to use JWT tokens

Result: After the Edit tool completes, you'll receive: "Tool: Edit completed"

Example 3: Running Commands

claude

> Run the test suite and fix any failing tests

Result: When the Bash tool finishes running tests, notification shows: "Tool: Bash completed"

System Requirements

The Simple Notifications Hook works on:

• macOS - Uses osascript (built-in, no installation needed)
• Linux - Uses notify-send (usually pre-installed, or install via package manager)

Installing notify-send on Linux:

# Debian/Ubuntu
sudo apt-get install libnotify-bin

# Fedora/RHEL
sudo dnf install libnotify

# Arch Linux
sudo pacman -S libnotify

How It Works

The hook uses Claude Code's PostToolUse event system:

• Matcher: "*" - Monitors ALL tool executions
• Trigger - Activates after each tool completes
• Command - Runs a shell command to display notification
• Variable: $CLAUDE_TOOL_NAME - Dynamically shows which tool was used

The hook automatically detects your operating system and uses the appropriate notification command.

Benefits of Desktop Notifications

• Stay Informed - Know exactly when long-running operations finish
• Multitask Efficiently - Work on other tasks while Claude Code processes
• Immediate Feedback - Get instant confirmation of completed actions
• Better Workflow - Reduce context switching and checking back on terminal
• Track Progress - Monitor multiple operations across different projects

Customization Options

You can customize the hook by editing .claude/hooks/simple-notifications.json:

{
  "description": "Send desktop notifications with custom messages",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read|Write|Edit",  // Only specific tools
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Custom Title' 'File operation: $CLAUDE_TOOL_NAME done!'"
          }
        ]
      }
    ]
  }
}

Troubleshooting

Notifications not appearing on macOS

Check that terminal has notification permissions:

1. Open System Preferences → Notifications & Focus
2. Find your terminal app (Terminal.app, iTerm2, etc.)
3. Enable "Allow Notifications"

Notifications not appearing on Linux

Ensure notify-send is installed:

# Check if notify-send exists
which notify-send

# Test notification manually
notify-send "Test" "This is a test notification"

Official Documentation

For more information about hooks in Claude Code, see the official hooks documentation.