Skip to main content
Glama
nkyy

Claude Code Notification Hooks

by nkyy
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

šŸ”” Claude Code Notification Hooks

āš ļø DEPRECATED: This project has been superseded by cat-ccnotify-hook. Please use the new standalone package for better performance and easier installation.

Enhanced Claude Code experience with automatic desktop notifications and contextual sounds for all events. No manual notification calls needed - works automatically with all Claude Code operations!

āœØ Features

  • šŸ”” Automatic Notifications: Intercepts ALL Claude Code notifications and enhances them

  • šŸŽµ Contextual Sounds: Different sounds for success, error, warning, and other event types

  • šŸš€ Zero Configuration: Automatic detection and enhancement of notification types

  • šŸ“‹ Smart Sound Mapping: Intelligent analysis of notification content for appropriate sounds

  • šŸ–±ļø Native System Integration: Uses macOS/Windows/Linux native notification systems

šŸš€ Quick Start

Method 1: One-Command Setup (Recommended)

Run this in Claude Code:

cd /path/to/ccnotify && npm run setup-hooks

Method 2: Manual Setup

  1. Clone and build:

git clone <this-repository> cd ccnotify npm install && npm run build

  1. Run setup:

npm run setup-hooks

  1. Restart Claude Code if it's currently running

3. That's It!

All Claude Code notifications will now automatically have enhanced sounds and styling. No additional configuration needed!

šŸ“± How It Works

The notification hook automatically detects and enhances all Claude Code notifications:

Automatic Sound Assignment

  • āœ… Success/Completion ā†’ Glass sound (macOS)

  • šŸšØ Errors/Failures ā†’ Basso sound (macOS)

  • āš ļø Warnings/Attention ā†’ Sosumi sound (macOS)

  • šŸ’” Info/Updates ā†’ Blow sound (macOS)

  • ā³ Progress/Ongoing ā†’ Tink sound (macOS)

Examples in Action

# Building a project npm run build # ā†’ Automatic success notification with Glass sound when complete # ā†’ Automatic error notification with Basso sound if failed # Running tests npm test # ā†’ Automatic progress notification with Tink sound while running # ā†’ Automatic completion notification when finished # Git operations git push origin main # ā†’ Automatic notifications for each step with appropriate sounds

šŸŽµ Available Sounds

Sound

Use Case

macOS Sound

success

Task completion, success

Glass

error

Errors, failures

Basso

warning

Warnings, attention needed

Sosumi

info

Information, status updates

Blow

progress

Progress updates, ongoing work

Tink

reminder

Reminders, prompts

Ping

default

System default notification sound

-

silent

No sound

-

šŸ› ļø Advanced Configuration

Customizing Sound Mappings

Edit the hook script at hooks/notification-hook.js to customize sound mappings:

// Example: Add custom sound rules const customSoundRules = [ { pattern: /deployment/i, sound: 'Ping' }, { pattern: /security/i, sound: 'Funk' }, { pattern: /backup/i, sound: 'Purr' } ];

Troubleshooting

Hook not working?

# Check if hook is properly installed cat ~/.config/claude-code/settings.json | grep -A 10 "hooks" # Verify hook script is executable ls -la hooks/notification-hook.js # Re-run setup if needed npm run setup-hooks

Sounds not playing?

# Test system sound (macOS) afplay /System/Library/Sounds/Glass.aiff # Check notification permissions in System Preferences

šŸŒ Real-World Examples

Automatic Enhancement Examples

Claude Code Operations ā†’ Enhanced Notifications

# File operations "Create a new React component" ā†’ āœ… "Component created successfully" + Glass sound # Build processes "Run the build process" ā†’ ā³ "Build in progress..." + Tink sound ā†’ āœ… "Build completed successfully" + Glass sound # Error scenarios "Fix the TypeScript errors" ā†’ šŸšØ "3 type errors found" + Basso sound # Git operations "Commit these changes" ā†’ āœ… "Changes committed successfully" + Glass sound

šŸ”§ Development

Development Commands

npm run dev # Development mode with auto-reload npm run build # Production build npm start # Start production server

Platform Support

  • macOS: Full native support with osascript and system sounds

  • Windows/Linux: Cross-platform support via node-notifier package

Architecture

  • Type-safe TypeScript implementation

  • MCP (Model Context Protocol) compliant

  • Automatic platform-specific implementation switching

  • Extensible notification type system

šŸ“‹ Technical Details

Hook Architecture

The notification hook intercepts Claude Code's notification system and enhances it:

  1. Interception: Hook receives all notification calls from Claude Code

  2. Analysis: Analyzes notification content using pattern matching

  3. Enhancement: Adds appropriate sounds and styling based on content

  4. Native Integration: Uses platform-specific notification APIs

Installation Structure

~/.config/claude-code/settings.json # Claude Code configuration hooks/notification-hook.js # Main hook script dist/index.js # Built MCP server (optional) scripts/setup-hooks.js # Automated setup script

Platform Support

  • macOS: Full native support with osascript and system sounds

  • Windows/Linux: Cross-platform support via node-notifier package

Legacy MCP Server (Optional)

For advanced users who want manual notification control, the MCP server is still available:

{ "mcpServers": { "ccnotify": { "command": "node", "args": ["/absolute/path/to/ccnotify/dist/index.js"] } } }

šŸ¤ Contributing

Bug reports and feature requests are welcome! Please open an issue.

šŸ“„ License

MIT License

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nkyy/claude-code-notify-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server