Metadata-Version: 2.4
Name: ccnotify
Version: 0.1.13
Summary: Intelligent notification system for Claude Code with audio feedback
Project-URL: Homepage, https://github.com/Helmi/CCNotify
Project-URL: Repository, https://github.com/Helmi/CCNotify
Project-URL: Issues, https://github.com/Helmi/CCNotify/issues
Project-URL: Documentation, https://github.com/Helmi/CCNotify#readme
Author-email: Frank Helmschrott <frank@helmschrott.de>
License: MIT
License-File: LICENSE
Keywords: audio,claude-code,notifications,productivity,tts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: kokoro-onnx>=0.3.9
Requires-Dist: pathlib2>=2.3.7; python_version < '3.11'
Requires-Dist: plyer>=2.1.0; sys_platform != 'darwin'
Requires-Dist: pydub>=0.25.1
Requires-Dist: pync>=2.0.3; sys_platform == 'darwin'
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: soundfile>=0.12.1
Requires-Dist: tqdm>=4.64.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: elevenlabs>=0.2.0; extra == 'full'
Description-Content-Type: text/markdown

# CCNotify

[![Latest Release](https://img.shields.io/github/v/release/Helmi/CCNotify)](https://github.com/Helmi/CCNotify/releases/latest)
[![PyPI](https://img.shields.io/pypi/v/ccnotify)](https://pypi.org/project/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.

```bash
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.

**Troubleshooting:** Use `uvx ccnotify install --force` to completely reinstall if you encounter issues.

### Logging

By default, CCNotify runs without logging to prevent log files from growing too large. If you need to debug issues or track activity, you can enable logging:

```bash
# Install with logging enabled
uvx ccnotify install --logging

# Update existing installation to enable logging
uvx ccnotify install --logging

# Update existing installation to disable logging (default)
uvx ccnotify install
```

When logging is enabled, log files will be created in `~/.claude/ccnotify/logs/` with daily rotation.

## 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](https://try.elevenlabs.io/ist8m7h95ed2).

## 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


## Configuration

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

**For Local TTS (Kokoro):**

```json
{
  "tts_provider": "kokoro",
  "voice": "af_heart",
  "speed": 1.0,
  "format": "mp3",
  "mp3_bitrate": "128k",
  "models_dir": "~/.claude/ccnotify/models"
}
```

> **Note:** `af_heart` is recommended as it provides the highest quality English pronunciation among Kokoro voices.

**For Cloud TTS (ElevenLabs):**

```json
{
  "tts_provider": "elevenlabs",
  "api_key": "your_api_key_here",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "model_id": "eleven_flash_v2_5"
}
```

**Voice Options:**

- **Kokoro**: `af_heart` (recommended), `af_sarah`, `am_adam`, `bf_alice`, `bm_daniel` and [40+ others](https://github.com/thewh1teagle/kokoro-onnx)
- **ElevenLabs**: Use voice IDs from your [ElevenLabs account](https://try.elevenlabs.io/ist8m7h95ed2)

**Pronunciation Customization:**

Customize how project names and commands are pronounced by editing `~/.claude/ccnotify/replacements.json`. CCNotify automatically discovers your projects and you can adjust their pronunciation:

```json
{
  "projects": {
    "ccnotify": {
      "folder": "-Users-helmi-code-ccnotify",
      "display_name": "CCNotify",
      "pronunciation": "CC notify"
    },
    "agent-zero": {
      "folder": "-Users-helmi-code-agent-zero",
      "display_name": "Agent Zero",
      "pronunciation": "agent zero"
    }
  },
  "commands": {
    "ls": "list",
    "cd": "change directory",
    "rm": "remove",
    "mkdir": "make directory",
    "npm": "N P M",
    "uvx": "U V X"
  },
  "patterns": [
    {
      "pattern": "npm run (\\w+)",
      "replacement": "N P M run {1}"
    },
    {
      "pattern": "git (push|pull|commit)",
      "replacement": "git {1}"
    },
    {
      "pattern": "(.+)\\.py",
      "replacement": "{1} python file"
    }
  ]
}
```

**Note:** Existing configurations will be automatically migrated to the new format on first load.

## Requirements

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

## Early Version Notice

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

**Issues & Suggestions**: Please use [GitHub Issues](https://github.com/Helmi/CCNotify/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
