cc-pushover

Send intelligent Pushover notifications when Claude Code needs your attention. Never miss an important decision or prompt while away from your terminal.

What It Does

cc-pushover integrates with Claude Code's Notification hook to send smart push notifications to your phone. It uses AI to decide which notifications matter, then sends you:

• AI-filtered alerts - Only notifies when Claude needs your input (uses OpenAI to filter routine messages)
• AI-generated summary - Concise summary of what Claude needs (using OpenAI's gpt-4.1-nano)
• Project context - Project name, path, and timestamp
• Full details - Complete notification text in Pushover

How it works:

1. Claude Code sends a notification (permission request, idle prompt, etc.)
2. cc-pushover asks OpenAI: "Does this need user attention?"
3. If yes → Summarizes and sends Pushover notification
4. If no → Exits silently (no spam!)

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager
• A Pushover account and application
• An OpenAI API key

Quick Start

1. Install with uvx (recommended):

   uvx --from git+https://github.com/yourusername/cc-pushover cc-pushover --init

2. Or install from source:

   git clone <repository-url>
   cd cc-pushover
   uv sync
   uv run cc-pushover --init

3. Get your credentials:

   • Pushover: Create an application at pushover.net/apps/build
     • Note your Application Token
     • Find your User Key in your dashboard
   • OpenAI: Create an API key at platform.openai.com/api-keys

4. Edit the config file that was just created:

   # See where the config is
   cc-pushover --config
   
   # Edit it (example for macOS/Linux)
   nano ~/.config/cc-pushover/config.toml

5. Add your credentials:

   [pushover]
   token = "your-pushover-application-token"
   user = "your-pushover-user-key"
   
   [openai]
   api_key = "sk-your-openai-api-key"
   model = "gpt-4.1-nano"  # Released April 2025 - fast and cheap
   max_summary_length = 100
   
   [notification]
   timeout_for_priority = 600  # Reserved for future use

Claude Code Integration

Setting Up the Hook

You need to add cc-pushover as a hook in your Claude Code configuration. There are two ways to do this:

Option 1: User-Level Hook (Recommended)

Add to your user config at ~/.claude/config.json:

{
  "hooks": {
    "Notification": {
      "command": "uvx cc-pushover",
      "blocking": false
    }
  }
}

This will work for ALL your Claude Code sessions.

Option 2: Project-Level Hook

Add to your project's .claude/config.json:

{
  "hooks": {
    "Notification": {
      "command": "uvx cc-pushover",
      "blocking": false
    }
  }
}

This only works for the specific project.

Hook Configuration Details

Important notes:

• The Notification hook fires on all Claude Code notifications (permission requests, idle prompts, etc.)
• OpenAI intelligently filters which ones warrant alerting you
• The blocking: false setting ensures the hook doesn't block Claude Code if it fails
• Hook input is passed via stdin as JSON with message, notification_type, and cwd fields

Testing the Hook

After setting up the hook, test it by asking Claude Code a question that requires your input. You should receive a Pushover notification within a few seconds.

Troubleshooting Hook Setup

If notifications aren't working:

1. Check the hook is configured:

   # User config
   cat ~/.claude/config.json
   
   # Or project config
   cat .claude/config.json

2. Test cc-pushover manually:

   CLAUDE_CODE_QUESTION="Test question?" CLAUDE_CODE_CWD="$(pwd)" uvx cc-pushover

3. Check Claude Code logs for errors when the hook fires

How It Works

1. Claude Code sends a notification (permission request, idle prompt, error, etc.)
2. The Notification hook triggers and calls cc-pushover
3. cc-pushover asks OpenAI: "Should the user be alerted about this?"
   • Checks notification type (idle_prompt, permission_prompt, etc.)
   • Analyzes the message content
   • Returns yes/no decision
4. If no → Exits silently (no spam!)
5. If yes → Summarizes the notification using OpenAI's gpt-4.1-nano
6. Extracts project context (name, path, timestamp)
7. Sends Pushover notification with summary and context

The notification won't block Claude Code - if there's an error, it logs to stderr and exits cleanly.

Command Line Interface

cc-pushover provides several helpful CLI commands:

Initialize Config

Create a template configuration file:

cc-pushover --init

This creates ~/.config/cc-pushover/config.toml with placeholders for your credentials.

Show Config Location

See where your config file is (or should be):

cc-pushover --config

Use Custom Config

Specify a different config file location:

cc-pushover --config /path/to/custom-config.toml

Show Help

cc-pushover --help

Send Test Notification

Test your Pushover setup by sending a test notification:

cc-pushover --test "Testing Pushover notifications!"

This sends a notification with your custom message and current project context.

Show Version

cc-pushover --version

Configuration

Config File

The configuration file is loaded from:

• $XDG_CONFIG_HOME/cc-pushover/config.toml (if XDG_CONFIG_HOME is set)
• ~/.config/cc-pushover/config.toml (default)

Environment Variables

You can override config file values with environment variables:

export PUSHOVER_TOKEN="your-token"
export PUSHOVER_USER="your-user-key"
export OPENAI_API_KEY="sk-your-key"

Environment variables take precedence over config file values.

Model Information

This project uses OpenAI's gpt-4.1-nano model, which was released in April 2025. It's optimized for:

• Fast response times (typically < 500ms)
• Low cost per request
• Simple summarization tasks

If you prefer a different model, you can change it in the config file.

Testing

Run the test suite:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest test_config.py

Test Coverage

The project includes comprehensive tests for:

• Configuration loading (file, environment variables, defaults)
• Question summarization (OpenAI integration, error handling)
• Pushover notifications (API calls, context extraction)
• Main integration flow (hook parsing, error handling)

Troubleshooting

"Missing required credentials" error

Make sure you've edited the config file and added your:

• Pushover application token
• Pushover user key
• OpenAI API key

Or set them as environment variables.

"No question found" error

This usually means the hook isn't configured correctly. Make sure:

• The CLAUDE_CODE_QUESTION environment variable is set to {{question}}
• The CLAUDE_CODE_CWD environment variable is set to {{cwd}}

OpenAI API errors

If you see "Invalid model" errors:

• Verify that gpt-4.1-nano is available in your OpenAI account
• Check your API key is valid and has credits
• Try a different model like gpt-3.5-turbo in the config

Pushover not receiving notifications

• Verify your Pushover app is installed on your phone
• Check that your application token and user key are correct
• Test your credentials at pushover.net

Permission errors

Make sure the script is executable:

chmod +x cc_pushover.py

Project Structure

cc-pushover/
� cc_pushover.py       # Main entry point and hook integration
� config.py            # Configuration loading and validation
� summarizer.py        # OpenAI integration for question summarization
� notifier.py          # Pushover API integration
� test_*.py            # Comprehensive test suite
� pyproject.toml       # uv project configuration
� README.md            # This file

License

MIT

Contributing

Contributions welcome! Please:

1. Write tests for new features
2. Follow the existing code style
3. Update the README if adding new features