Claude Code Pushover Notifications

Send push notifications to your mobile device when Claude Code events occur (idle prompts, permission requests, stops, etc).

Read the PUSHOVER_NOTIFICATIONS_README.md for more details, and DAEMON.md (Dutch) for how the daemon works and how to manage it.

Features

• Event Hook Integration: Integrates with Claude Code hooks system
• Rate Limited: Maximum 1 notification per 30 seconds to avoid spam
• Daily Limit: Maximum 90 notifications per day by default, to stay within Pushover's monthly message limit
• Priority Queue: Stop and PermissionRequest events are queued and sent when rate limit allows
• Daemon Process: Runs as a background daemon to handle notifications
• Configurable: Uses environment variables for API credentials

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Pushover

1. Sign up for a free account at pushover.net
2. Install the Pushover app on your mobile device
3. Create a new application at pushover.net/apps
4. Note your User Key (from your dashboard) and App Token (from your new app)

3. Configure Environment Variables

mkdir -p ~/.config/claude-pushover
cp .env.example ~/.config/claude-pushover/config.env
chmod 600 ~/.config/claude-pushover/config.env

Edit ~/.config/claude-pushover/config.env and add your Pushover credentials (a .env file in the repo directory also works as a fallback):

PUSHOVER_USER_KEY=your_user_key_here
PUSHOVER_APP_TOKEN=your_app_token_here

4. Start the Daemon

On macOS, install it as a LaunchAgent so it starts automatically at login and restarts if it crashes:

./install.sh

This copies the daemon and hook to ~/.local/share/claude-pushover, creates a virtualenv there and registers ~/Library/LaunchAgents/local.claude-pushover.plist. Logs go to ~/Library/Logs/claude-pushover.log. Run ./install.sh again after pulling updates, or ./install.sh uninstall to remove it.

Alternatively, start it manually:

python3 claude_pushover_daemon.py

Or run it as a background service using the provided script:

./claude_pushover_service.sh start

5. Configure Claude Code Hook

Add the following to your Claude Code hooks configuration:

{
  "hooks": {
    "notification": "./claude_hook.py",
    "stop": "./claude_hook.py",
    "permission_request": "./claude_hook.py"
  }
}

Files

• claude_hook.py: Hook script that receives Claude Code events and forwards to daemon
• claude_pushover_daemon.py: Background daemon that sends rate-limited notifications
• pushover_notifications.py: Standalone script for testing Pushover notifications
• claude_pushover_service.sh: Service management script for the daemon

Usage

Once configured, the daemon will automatically send notifications when:

• Claude Code is waiting for your input and you haven't responded for about a minute (idle_prompt)
• Claude Code requests permission (PermissionRequest)

Optionally, set these in ~/.config/claude-pushover/config.env and restart the daemon:

• NOTIFY_ON_STOP=true: also notify every time Claude finishes a response (off by default, because it fires after every response)
• NOTIFICATION_TYPES=idle_prompt,permission_prompt: which Notification types to send (default idle_prompt; permission_prompt duplicates PermissionRequest)
• MAX_NOTIFICATIONS_PER_DAY=90: daily cap, 0 for unlimited

Rate Limiting

To prevent notification spam, the daemon enforces a 30-second rate limit between notifications and a daily cap (MAX_NOTIFICATIONS_PER_DAY, default 90). Events over the daily cap are dropped; the count is kept in ~/.local/state/claude-pushover/daily_count.json so restarts don't reset it.

• Stop and PermissionRequest events are queued and sent after the rate limit expires
• Notification events are dropped if received during the rate limit window

Testing

Test your Pushover configuration with:

python3 pushover_notifications.py

This will send test notifications to verify your setup.

License

MIT License - feel free to modify and distribute