CCNotify

Voice Notification System for Claude Code

🗣️ Have your favourite Voide tell you what's up in Claude Code ⁉ Get notified when your Input is needed ⚠ Be aware of critical commands being executed 🏃‍♂️ Stay in control of multiple agents 🕵🏻‍♂️ Select between local TTS (Kokoro) and Elevenlabs (more to come) 💡 Sound caching system to save on API Credity/Processing time

NOTE: This is an early stage project I primarily designed around my own use cases.

❤️ Your input through Github Issues is highly appreciated.

Platforms

Currently CCNotify is only tested on MacOS (15.5). Help testing or implementing other Platforms. PRs welcome.

Quick Start

Interactive installer - guides you through everything. All you need is Python and UV installed.

uvx ccnotify install

That's it! The installer will:

• Help you choose between local (Kokoro) or cloud (ElevenLabs) TTS
• Download models if needed
• Install hooks into Claude Code
• Create a configuration file
• Guide you through next steps

Restart Claude Code to enable notifications.

Support the work

If you want to support the project or me in Person, feel free to become a Github Sponsor.

If you use Elevenlabs as a TTS provider, use my Affiliate link to signup.

Features

• Smart Filtering: Only notifies for significant events, not routine operations
• Dual TTS Options: Local Kokoro models (50+ voices) or ElevenLabs cloud API
• Project Detection: Automatically identifies your current project
• Zero Config: Works out of the box with sensible defaults
• Privacy First: Local processing with optional cloud TTS

Commands

# Single intelligent install command - handles everything automatically
uvx ccnotify install                     # Install or update CCNotify intelligently
uvx ccnotify install --force             # Force complete reinstallation
uvx ccnotify install --config-only       # Only update configuration
uvx ccnotify install --quiet             # Minimal output mode

The new installer automatically detects:

• Whether CCNotify is already installed (runs update flow)
• What TTS provider you prefer
• Whether models need downloading
• Configuration migration needs

That's it! No more complex subcommands - just one command that does the right thing.

Configuration

The installer creates a configuration file at ~/.claude/ccnotify/config.json. Key settings:

For Local TTS (Kokoro):

{
  "tts": { "provider": "kokoro", "enabled": true },
  "kokoro": {
    "voice": "af_sarah",
    "speed": 1.0,
    "models_dir": "models"
  }
}

For Cloud TTS (ElevenLabs):

{
  "tts": { "provider": "elevenlabs", "enabled": true },
  "elevenlabs": {
    "api_key": "your_api_key_here",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "model_id": "eleven_flash_v2_5"
  }
}

Voice Options:

• Kokoro: af_sarah, am_adam, bf_alice, bm_daniel and 40+ others
• ElevenLabs: Use voice IDs from your ElevenLabs account

Requirements

• macOS or Linux
• Python 3.9+
• Claude Code CLI
• For Kokoro: ~350MB disk space for local models
• For ElevenLabs: API account and internet connection

Early Version Notice

This is v0.1.0 - an early release focused on core functionality. Features may change based on feedback.

Issues & Suggestions: Please use GitHub Issues to report problems or suggest improvements.

How It Works

CCNotify hooks into Claude Code's tool execution events and provides audio notifications for:

• Potentially risky operations (file deletions, system commands)
• Task completion
• Error conditions
• Input requirements

The system filters out routine operations to avoid notification fatigue while keeping you informed of important events during long-running AI sessions.

License

MIT