Claude Code Notify Lite

Task completion notifications for Claude Code - Cross-platform, lightweight, and easy to use.

English | 中文

Features

• Cross-platform - Works on Windows, macOS, and Linux
• Lightweight - Minimal dependencies, fast startup
• Easy to use - One command installation
• Customizable - Choose your notification sound
• Non-intrusive - Integrates seamlessly with Claude Code

Quick Start

Using npm (Recommended)

npm install -g claude-code-notify-lite
ccnotify install

If ccnotify command is not found, use npx instead:

npx claude-code-notify-lite install

Or add npm global bin to your PATH:

Windows: Add %APPDATA%\npm to your PATH environment variable.

macOS/Linux: Add $(npm root -g)/../bin to your PATH.

Using install script

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/waterpen6/claude-code-notify-lite/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/waterpen6/claude-code-notify-lite/main/scripts/install.ps1 | iex

Usage

After installation, notifications will automatically appear when Claude Code completes a task.

Commands

# Test notification
ccnotify test

# Check installation status
ccnotify status

# Configure settings interactively
ccnotify config

# List available sounds
ccnotify sounds

# Uninstall
ccnotify uninstall

Configuration

Configuration file location:

• Windows: %APPDATA%\claude-code-notify-lite\config.json
• macOS: ~/Library/Application Support/claude-code-notify-lite/config.json
• Linux: ~/.config/claude-code-notify-lite/config.json

Options

{
  "notification": {
    "enabled": true,
    "title": "Claude Code",
    "showWorkDir": true,
    "showTime": true
  },
  "sound": {
    "enabled": true,
    "file": "default",
    "volume": 80
  }
}

Custom Sound

You can use a custom sound file:

{
  "sound": {
    "file": "/path/to/your/sound.mp3"
  }
}

Supported formats: MP3, WAV, M4A, OGG

How It Works

Claude Code Notify Lite integrates with Claude Code's hook system:

1. When you run ccnotify install, it adds a Stop hook to your Claude Code settings
2. When Claude Code completes a task, it triggers the hook
3. The hook sends a system notification and plays a sound

Troubleshooting

Debug Logs

View debug logs to diagnose issues:

# Show recent logs
ccnotify logs

# Show more lines
ccnotify logs -n 100

# Clear logs
ccnotify logs -c

Log file locations:

• Windows: %APPDATA%\claude-code-notify-lite\debug.log
• macOS: ~/Library/Logs/claude-code-notify-lite/debug.log
• Linux: ~/.local/state/claude-code-notify-lite/debug.log

Command 'ccnotify' not found

After npm global install, if ccnotify is not recognized:

# Use npx instead (short form)
npx ccnotify install

# Or use full package name
npx claude-code-notify-lite install

# Or find npm global bin location
npm root -g
# Then add the parent bin directory to PATH

Hook error: "path not found"

If you see garbled text like "ϵͳ找不到指定的路径" in hook errors:

# Reinstall to update hook command with absolute paths
npx ccnotify uninstall
npx ccnotify install

The latest version uses absolute paths (node.exe + cli.js) instead of npx, which resolves PATH issues in hook execution environment.

Notification not showing

macOS:

• Go to System Settings > Notifications
• Find "Terminal" (or your terminal app) and enable notifications

Windows:

• Go to Settings > System > Notifications
• Ensure notifications are enabled

Sound not playing

• Check system volume
• Verify the sound file exists: ccnotify sounds
• Try a different sound: ccnotify config

Hook not working

# Check installation status
ccnotify status

# Reinstall if needed
ccnotify uninstall
ccnotify install

Uninstall

ccnotify uninstall
npm uninstall -g claude-code-notify-lite

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT