# CCNotify
[](https://github.com/Helmi/CCNotify/releases/latest)
[](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
Raw data
{
"_id": null,
"home_page": null,
"name": "ccnotify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "audio, claude-code, notifications, productivity, tts",
"author": null,
"author_email": "Frank Helmschrott <frank@helmschrott.de>",
"download_url": "https://files.pythonhosted.org/packages/b9/c8/3cf211a7227552615361b9e790b03b81f91eebe2da66c278ac61aadf8109/ccnotify-0.1.13.tar.gz",
"platform": null,
"description": "# CCNotify\n\n[](https://github.com/Helmi/CCNotify/releases/latest)\n[](https://pypi.org/project/ccnotify/)\n\n## Voice Notification System for Claude Code\n\n- \ud83d\udde3\ufe0f Have your favourite Voide tell you what's up in Claude Code\n- \u2049 Get notified when your Input is needed\n- \u26a0 Be aware of critical commands being executed\n- \ud83c\udfc3\u200d\u2642\ufe0f Stay in control of multiple agents\n- \ud83d\udd75\ud83c\udffb\u200d\u2642\ufe0f Select between local TTS (Kokoro) and Elevenlabs (more to come)\n- \ud83d\udca1 Sound caching system to save on API Credity/Processing time\n\n**NOTE:** This is an early stage project I primarily designed around my own use cases.\n\n\u2764\ufe0f Your input through Github Issues is highly appreciated.\n\n## Platforms\n\nCurrently CCNotify is only tested on MacOS (15.5). Help testing or implementing other Platforms. PRs welcome.\n\n## Quick Start\n\nInteractive installer - guides you through everything. All you need is Python and UV installed.\n\n```bash\nuvx ccnotify install\n```\n\nThat's it! The installer will:\n\n- Help you choose between local (Kokoro) or cloud (ElevenLabs) TTS\n- Download models if needed\n- Install hooks into Claude Code\n- Create a configuration file\n- Guide you through next steps\n\nRestart Claude Code to enable notifications.\n\n**Troubleshooting:** Use `uvx ccnotify install --force` to completely reinstall if you encounter issues.\n\n### Logging\n\nBy 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:\n\n```bash\n# Install with logging enabled\nuvx ccnotify install --logging\n\n# Update existing installation to enable logging\nuvx ccnotify install --logging\n\n# Update existing installation to disable logging (default)\nuvx ccnotify install\n```\n\nWhen logging is enabled, log files will be created in `~/.claude/ccnotify/logs/` with daily rotation.\n\n## Support the work\n\nIf you want to support the project or me in Person, feel free to become a Github Sponsor.\n\nIf you use Elevenlabs as a TTS provider, [use my Affiliate link to signup](https://try.elevenlabs.io/ist8m7h95ed2).\n\n## Features\n\n- **Smart Filtering**: Only notifies for significant events, not routine operations\n- **Dual TTS Options**: Local Kokoro models (50+ voices) or ElevenLabs cloud API\n- **Project Detection**: Automatically identifies your current project\n- **Zero Config**: Works out of the box with sensible defaults\n- **Privacy First**: Local processing with optional cloud TTS\n\n\n## Configuration\n\nThe installer creates a configuration file at `~/.claude/ccnotify/config.json`. Key settings:\n\n**For Local TTS (Kokoro):**\n\n```json\n{\n \"tts_provider\": \"kokoro\",\n \"voice\": \"af_heart\",\n \"speed\": 1.0,\n \"format\": \"mp3\",\n \"mp3_bitrate\": \"128k\",\n \"models_dir\": \"~/.claude/ccnotify/models\"\n}\n```\n\n> **Note:** `af_heart` is recommended as it provides the highest quality English pronunciation among Kokoro voices.\n\n**For Cloud TTS (ElevenLabs):**\n\n```json\n{\n \"tts_provider\": \"elevenlabs\",\n \"api_key\": \"your_api_key_here\",\n \"voice_id\": \"21m00Tcm4TlvDq8ikWAM\",\n \"model_id\": \"eleven_flash_v2_5\"\n}\n```\n\n**Voice Options:**\n\n- **Kokoro**: `af_heart` (recommended), `af_sarah`, `am_adam`, `bf_alice`, `bm_daniel` and [40+ others](https://github.com/thewh1teagle/kokoro-onnx)\n- **ElevenLabs**: Use voice IDs from your [ElevenLabs account](https://try.elevenlabs.io/ist8m7h95ed2)\n\n**Pronunciation Customization:**\n\nCustomize how project names and commands are pronounced by editing `~/.claude/ccnotify/replacements.json`. CCNotify automatically discovers your projects and you can adjust their pronunciation:\n\n```json\n{\n \"projects\": {\n \"ccnotify\": {\n \"folder\": \"-Users-helmi-code-ccnotify\",\n \"display_name\": \"CCNotify\",\n \"pronunciation\": \"CC notify\"\n },\n \"agent-zero\": {\n \"folder\": \"-Users-helmi-code-agent-zero\",\n \"display_name\": \"Agent Zero\",\n \"pronunciation\": \"agent zero\"\n }\n },\n \"commands\": {\n \"ls\": \"list\",\n \"cd\": \"change directory\",\n \"rm\": \"remove\",\n \"mkdir\": \"make directory\",\n \"npm\": \"N P M\",\n \"uvx\": \"U V X\"\n },\n \"patterns\": [\n {\n \"pattern\": \"npm run (\\\\w+)\",\n \"replacement\": \"N P M run {1}\"\n },\n {\n \"pattern\": \"git (push|pull|commit)\",\n \"replacement\": \"git {1}\"\n },\n {\n \"pattern\": \"(.+)\\\\.py\",\n \"replacement\": \"{1} python file\"\n }\n ]\n}\n```\n\n**Note:** Existing configurations will be automatically migrated to the new format on first load.\n\n## Requirements\n\n- macOS or Linux\n- Python 3.10+\n- Claude Code CLI\n- **For Kokoro**: ~350MB disk space for local models\n- **For ElevenLabs**: API account and internet connection\n\n## Early Version Notice\n\nThis is an early release focused on core functionality. Features may change based on feedback.\n\n**Issues & Suggestions**: Please use [GitHub Issues](https://github.com/Helmi/CCNotify/issues) to report problems or suggest improvements.\n\n## How It Works\n\nCCNotify hooks into Claude Code's tool execution events and provides audio notifications for:\n\n- Potentially risky operations (file deletions, system commands)\n- Task completion\n- Error conditions\n- Input requirements\n\nThe system filters out routine operations to avoid notification fatigue while keeping you informed of important events during long-running AI sessions.\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligent notification system for Claude Code with audio feedback",
"version": "0.1.13",
"project_urls": {
"Documentation": "https://github.com/Helmi/CCNotify#readme",
"Homepage": "https://github.com/Helmi/CCNotify",
"Issues": "https://github.com/Helmi/CCNotify/issues",
"Repository": "https://github.com/Helmi/CCNotify"
},
"split_keywords": [
"audio",
" claude-code",
" notifications",
" productivity",
" tts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2ca0190f797d12f805cfede29f5b3e50b58a95f896130dda150b28a09ca663d0",
"md5": "e2139e23f1a1d3d9fb54bb3d684f3e1f",
"sha256": "465d641f47298037ea12646b0b03f08a5127481ec34e7419629f625e14ffc2b7"
},
"downloads": -1,
"filename": "ccnotify-0.1.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2139e23f1a1d3d9fb54bb3d684f3e1f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 47586,
"upload_time": "2025-08-10T11:38:30",
"upload_time_iso_8601": "2025-08-10T11:38:30.325680Z",
"url": "https://files.pythonhosted.org/packages/2c/a0/190f797d12f805cfede29f5b3e50b58a95f896130dda150b28a09ca663d0/ccnotify-0.1.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b9c83cf211a7227552615361b9e790b03b81f91eebe2da66c278ac61aadf8109",
"md5": "10b91f95bbe442e789b0d39a1d86a414",
"sha256": "3abee81c042b066b47076ef80de239d655e1cca6cb97398eca1e45f38cb2d368"
},
"downloads": -1,
"filename": "ccnotify-0.1.13.tar.gz",
"has_sig": false,
"md5_digest": "10b91f95bbe442e789b0d39a1d86a414",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 165929,
"upload_time": "2025-08-10T11:38:31",
"upload_time_iso_8601": "2025-08-10T11:38:31.657075Z",
"url": "https://files.pythonhosted.org/packages/b9/c8/3cf211a7227552615361b9e790b03b81f91eebe2da66c278ac61aadf8109/ccnotify-0.1.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 11:38:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Helmi",
"github_project": "CCNotify#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ccnotify"
}
JSON
