ccalert

🔔 Get desktop notifications when Claude Code completes your prompts

Overview

ccalert monitors Claude Code activity and sends desktop notifications when prompts complete. Never miss when Claude finishes processing your requests while you're working on other tasks.

Installation

npm install -g ccalert

Usage

Simply run in your terminal:

ccalert

The program automatically detects Claude Code sessions and starts monitoring.

Example Output

🔍 Starting Claude Code monitor...
✅ Monitoring active session:
   Project: my-awesome-project
   Log file: 4fdca8e1-c6fc-4f99-8a07-30c475462ffc.jsonl
   File size: 318.3 KB
✅ Monitoring Claude Code activity...
Press Ctrl+C to stop monitoring

📝 File changed, checking for completions...
   → Assistant message, has text: true
   → Timer set for 4 seconds...
   → COMPLETION DETECTED! (4s timeout after last assistant message)

🔔 [3:45:12 PM] Claude Code prompt completed!

Features

• 🔔 Cross-platform notifications - Works on macOS, Windows, and Linux
• 🔍 Auto-detection - Automatically finds Claude Code log files
• 📊 Real-time monitoring - Detects changes instantly
• 🎯 Simple interface - Just one command to run
• ⏱️ Smart completion detection - Uses 10-second timeout after last assistant message

How It Works

1. Monitors JSONL log files in ~/.claude/projects/
2. Detects when Claude Code stops sending messages for 10 seconds
3. Sends desktop notification via system notification API

Platform-Specific Setup

macOS

For notifications to work on macOS, you need to grant permission to your terminal app:

1. Open System Settings → Notifications
2. Find your terminal app (Terminal, iTerm2, Warp, etc.)
3. Enable Allow Notifications
4. Set alert style to Banners (recommended)
5. Enable Play sound for notifications

Test notifications:

npx node-notifier-cli notify -t "Test" -m "Notifications are working!"

Windows

Notifications should work out of the box on Windows 10/11.

Linux

Requires notify-send to be installed:

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

# Fedora
sudo dnf install libnotify

# Arch
sudo pacman -S libnotify

Troubleshooting

Notifications not working?

macOS:

• Check notification permissions in System Settings
• Make sure Do Not Disturb is off
• Restart your terminal after changing settings

All platforms:

• Ensure Claude Code has been run at least once
• Check if ~/.claude/projects/ directory exists
• Look for active sessions within the last 24 hours

Debug output

The tool provides detailed debug information:

• 📊 Shows new content size when files change
• → Displays each log entry type
• → Indicates when timers are set and completions detected

Requirements

• Node.js >= 14.0.0
• Claude Code installed and run at least once

License

MIT

Contributing

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

Made with ❤️ for Claude Code users