Task completion notifications for Claude Code - Cross-platform, lightweight, and easy to use
npm install claude-code-notify-litebash
npm install -g claude-code-notify-lite
ccnotify install
`
If ccnotify command is not found, use npx instead:
`bash
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.
$3
macOS / Linux:
`bash
curl -fsSL https://raw.githubusercontent.com/waterpen6/claude-code-notify-lite/main/scripts/install.sh | bash
`
Windows (PowerShell):
`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.
$3
`bash
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
$3
`json
{
"notification": {
"enabled": true,
"title": "Claude Code",
"showWorkDir": true,
"showTime": true
},
"sound": {
"enabled": true,
"file": "default",
"volume": 80
}
}
`
$3
You can use a custom sound file:
`json
{
"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
$3
View debug logs to diagnose issues:
`bash
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
$3
After npm global install, if ccnotify is not recognized:
`bash
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
`
$3
If you see garbled text like "ϵͳ找不到指定的路径" in hook errors:
`bash
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.
$3
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
$3
- Check system volume
- Verify the sound file exists: ccnotify sounds
- Try a different sound: ccnotify config
$3
`bash
Check installation status
ccnotify status
Reinstall if needed
ccnotify uninstall
ccnotify install
`
Uninstall
`bash
ccnotify uninstall
npm uninstall -g claude-code-notify-lite
``