cc-pushover

Send Pushover notifications from Claude Code hooks. Get notified on your phone when Claude needs permission, finishes a task, or executes tools.

Features

- 🔐 Permission prompts — Get notified when Claude needs your approval
- 💤 Idle alerts — Know when Claude has been waiting for 60+ seconds
- ✨ Task completion — Get notified when Claude finishes responding, with your last prompt included
- 🔧 Tool execution — Optionally track when specific tools run (Bash, Write, Edit, etc.)
- 📁 Project identification — Each notification shows which project triggered it
- 🔕 Smart deduplication — Stop notifications only fire once per conversation turn

Prerequisites

1. Bun — Install from bun.sh
2. Pushover account — Sign up at pushover.net
3. Pushover app — Create an application at pushover.net/apps (upload a Claude logo as the app icon for better notifications)

Installation

No installation needed! Run directly with bunx:

``bash
bunx cc-pushover init
`

Or install globally:

`bash
bun install -g cc-pushover
`

For local development:

`bash
git clone
cd cc-pushover
bun install
bun link
`

Setup

$3

Add these to your shell profile (.zshrc, .bashrc, etc.):

`bash
export PUSHOVER_APP_TOKEN=your_app_token # From pushover.net/apps
export PUSHOVER_USER_KEY=your_user_key # From pushover.net dashboard
`

Important: Make sure to export the variables so child processes (like Bun) can access them.

$3

`bash
cc-pushover init
`

This will:

- Let you choose which events to notify (Notification ✓, Stop ✓, PostToolUse ○)
- For PostToolUse, let you select all tools or specific ones
- Let you choose the scope (user settings or project settings)
- Write the hook configuration to your Claude Code settings

$3

Either restart Claude Code or run /hooks in the Claude Code prompt to reload the configuration.

Commands

$3

Interactive setup wizard to configure hooks:

`bash
cc-pushover init
`

$3

Send a test notification to verify your Pushover setup:

`bash
cc-pushover test
`

$3

Show current configuration and credential status:

`bash
cc-pushover status
`

$3

Remove cc-pushover hooks from settings:

`bash
cc-pushover uninstall
`

Notification Examples

| Event | Title | Message Example |
| ----------------- | ---------------------- | --------------------------------------------------- |
| Permission prompt | 🔐 Permission Required | [my-project] Claude wants to run: npm install |
| Idle prompt | 💤 Claude is Idle | [my-project] Claude has been idle for 60+ seconds |
| Task completed | ✨ Task Completed | [my-project] "Add unit tests for the hook module" |
| Tool executed | 🔧 Tool Executed | [my-project] Bash: \npm test\ completed. |

Configuration

Hooks are stored in Claude Code settings files:

- User settings: ~/.claude/settings.json — applies to all projects
- Project settings: .claude/settings.json — only the current project

Example generated configuration:

`json
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "bunx cc-pushover-hook",
"timeout": 30
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "bunx cc-pushover-hook",
"timeout": 30
}
]
}
]
}
}
`

Environment Variables

| Variable | Required | Description |
| -------------------- | -------- | ----------------------------------- |
| PUSHOVER_APP_TOKEN | Yes | Your Pushover application API token |
| PUSHOVER_USER_KEY | Yes | Your Pushover user key |

How It Works

1. Claude Code hooks call cc-pushover-hook` when events occur
2. The hook reads event data from stdin (JSON format)
3. It formats a notification with emoji, project name, and relevant details
4. Sends to Pushover API, which delivers to your phone

For Stop events, the hook uses smart deduplication: it hashes the last user message and only sends one notification per conversation turn, preventing duplicate alerts.

License

MIT