Automated Simple Notifications

Delivers desktop notifications for every tool completion using native OS notification systems on macOS and Linux.

When to Use This Hook

Attach this hook when you need to:

• Receive immediate desktop alerts when Claude Code completes any tool operation so you can multitask without constantly watching the terminal
• Stay informed about session progress while working in other applications, especially during long-running background operations
• Set up lightweight notification infrastructure without configuring external services like Discord, Slack, or email

Consider alternatives when:

• You need notification filtering and only want alerts for specific tool types rather than every single tool completion
• Your workflow requires persistent notification history or cross-device delivery that desktop notifications cannot provide

Quick Start

Configuration

Copy
name: automated-simple-notifications
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
# Any tool completion triggers a notification:
# Claude runs an Edit operation
# Desktop notification appears:
# Title: "Claude Code"
# Body: "Tool: Edit completed"

Example Output

[macOS Notification Center]
Title: Claude Code
Body: Tool: Edit completed

[Linux notify-send]
Title: Claude Code
Body: Tool: Bash completed

[Fallback - no notification system]
(silent - no error, no output)

Core Concepts

Notification System Overview

Aspect	Details
macOS Method	osascript -e 'display notification' via AppleScript
Linux Method	notify-send command from libnotify package
Trigger	PostToolUse with wildcard matcher catches all tool completions
Content	Tool name from $CLAUDE_TOOL_NAME environment variable
Fallback	Silently skips notification if neither osascript nor notify-send is available
Latency	Notification appears within 100-200ms of tool completion

Notification Delivery Workflow

Tool Operation Completes
    |
    v
[PostToolUse fires with matcher: *]
    |
    v
[Check OS notification capability]
    |
    +--- macOS? --> [osascript: display notification]
    |                   |
    |                   v
    |              [Notification Center shows alert]
    |
    +--- Linux? --> [notify-send command]
    |                   |
    |                   v
    |              [Desktop notification daemon shows alert]
    |
    +--- Neither --> [Silent skip, no error]

Configuration

Parameter	Type	Default	Description
matcher	string	*	Tool name pattern to trigger notifications; * matches all tools
notification_title	string	Claude Code	Title text displayed in the desktop notification header
include_file_path	boolean	false	Whether to append the affected file path to the notification body
sound	boolean	false	Whether to play a notification sound on macOS (not supported on all Linux DEs)
timeout	integer	5	Seconds before the notification auto-dismisses on Linux systems

Best Practices

1. Filter by tool type to reduce noise - The wildcard matcher sends a notification for every tool use, which can produce dozens of alerts per minute during active editing. Change the matcher to specific tools like Bash|Write to only receive notifications for operations that typically take longer.

2. Enable sound for critical operations only - On macOS, adding sound name "Glass" to the osascript command provides an audible alert. Reserve sound notifications for important events to prevent auditory overload during intensive coding sessions.

3. Test notification permissions on macOS - macOS may silently suppress notifications from terminal applications if notification permissions have not been granted. Open System Settings > Notifications and verify that Terminal or your terminal emulator has notification access enabled.

4. Install libnotify on Linux distributions - The notify-send command is not installed by default on all Linux distributions. Install it with sudo apt install libnotify-bin on Debian/Ubuntu or the equivalent package for your distribution before relying on this hook.

5. Combine with Do Not Disturb for focused work - When you need uninterrupted focus time, enable your OS Do Not Disturb mode. The hook continues to fire silently, and notifications will be available in the notification center when you return, providing a session activity summary.

Common Issues

1. No notifications appearing on macOS - macOS requires notification permissions for the terminal application. Check System Settings > Notifications and ensure your terminal emulator (Terminal, iTerm2, Ghostty) is listed and has alerts enabled. Also verify Focus mode is not suppressing notifications.

2. Notifications appear but dismiss too quickly on Linux - The default timeout for notify-send varies by desktop environment. Add --expire-time=10000 to the notify-send command to keep notifications visible for 10 seconds, or use --expire-time=0 for persistent notifications that require manual dismissal.

3. Hook slows down rapid editing sessions - On systems where the notification command has high latency, firing after every tool use can noticeably slow down rapid Edit operations. Add an async execution wrapper or restrict the matcher to long-running tools like Bash to eliminate the latency impact on editing workflows.