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:

bunx cc-pushover init

Or install globally:

bun install -g cc-pushover

For local development:

git clone <repo-url>
cd cc-pushover
bun install
bun link

Setup

1. Set environment variables

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

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.

2. Run the setup wizard

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. Reload Claude Code

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

Commands

init

Interactive setup wizard to configure hooks:

cc-pushover init

test

Send a test notification to verify your Pushover setup:

cc-pushover test

status

Show current configuration and credential status:

cc-pushover status

uninstall

Remove cc-pushover hooks from settings:

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:

{
  "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