ccnoti

Cross-Channel Notification CLI with sound, voice, and desktop alerts.

Features

• 🔊 Sound Effects: Audio playback with system sounds
• 🗣️ Voice Announcements: Text-to-speech notifications
• 📬 Visual Notifications: Native desktop notifications
• ⚙️ Configurable: Customizable via .ccnotirc configuration file

Installation

npm install -g ccnoti
# or
npx ccnoti [options]

Quick Start

Basic Usage

npx ccnoti -d -m "Task complete"     # Desktop notification (with sound)
npx ccnoti -d -v  -m "All tests pass" # Sound + Desktop notification
npx ccnoti -v -m "Deploy complete"   # Voice only
npx ccnoti -s                        # Sound only
npx ccnoti -s -V 0.3                # Sound with low volume (30%)
npx ccnoti -s -V 1.0                # Sound with max volume

Command Line Options

| Option | Alias | Description | Example | |--------|-------|-------------|---------| | --sound | -s | Play sound effect | --sound | | --voice | -v | Enable text-to-speech | --voice | | --desktop | -d | Show Desktop notification | --desktop | | --soundFile <path> | - | Sound file path to play | --soundFile=/System/Library/Sounds/Glass.aiff | | --volume <num> | -V | Sound volume (0.0-1.0) | --volume 0.5 | | --message <text> | -m | Notification message text | --message "Task done" | | --config <path> | -c | Path to config file | --config my-config.json |

Configuration File

Create a .ccnotirc file in your project root (automatically loaded):

{
  "sound": true,
  "voice": true,
  "desktop": false,
  "soundFile": "/System/Library/Sounds/Glass.aiff",
  "volume": 0.5
}

Or specify a custom config file with -c:

npx ccnoti -c my-config.json -m "Custom config"

Note: Command line options always override configuration file settings.

Integration with Claude Code Hooks

You can use ccnoti with Claude Code hooks to get notifications during your coding sessions. Add the following to your Claude Code configuration:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx ccnoti@latest --sound --voice --desktop -m 'Waiting for input'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx ccnoti@latest --sound --voice --desktop -m 'Task completed'"
          }
        ]
      }
    ]
  }
}

This configuration will:

• Notification hook: Play a notification when Claude is waiting for your input
• Stop hook: Play a notification when Claude has completed a task

You can customize the message and notification types (sound, voice, desktop) according to your preferences.

Platform Support

• macOS/Windows: Full support (sound, voice, desktop notifications)
• Linux: Desktop notifications only

Text-to-Speech

• macOS: System voices (e.g., Samantha, Daniel, Kyoko). List all: say -v ?
• Windows: SAPI voices (varies by system)
• Linux: Requires Festival (apt-get install festival)

Requirements

• Node.js >= 22
• Supported platforms:
  • macOS: sound, voice, notifications
  • Windows: sound, voice, notifications
  • Linux: notifications only

Dependencies

• citty: CLI framework
• c12: Configuration loader
• consola: Logging
• defu: Object merging
• node-notifier: Desktop notifications
• say: Text-to-speech
• sound-play: Sound playback
• pathe: Path utilities
• unbuild: Build tool

License

MIT License @kira_puka@Memory Lovers, LLC

Contributing

Issues and PRs welcome at github.com/memorylovers/ccnoti