Claudette

A sophisticated AI voice assistant with 1940s British charm

PyPI • Features • Installation • Configuration • Usage • Skills • Contributing • Support

---

Claudette is a voice-activated assistant that brings the elegance of a 1940s British bombshell to your command line. She listens for her wake word, transcribes your speech using Whisper, and responds with wit and charm through Claude CLI.

Features

• Wake Word Detection - Say "Claudette" to activate (with fuzzy matching for accents)
• Voice Activity Detection - Uses Silero VAD with GPU acceleration
• Speech-to-Text - Local (faster-whisper) or remote Whisper API
• Natural Conversation - Maintains conversation memory across sessions
• Text-to-Speech - Streaming TTS with multiple voice options
• Sound Effects - Audio feedback for state changes
• Hotkey Activation - Ctrl+Shift+C (or Cmd+Shift+C on Mac)
• System Tray - Status icon with waveform visualization
• Desktop Notifications - Optional notification support
• System Commands - Volume, battery, screenshots, and more
• Custom Skills - Extensible plugin system
• Multiple Personalities - Switch between different AI personas
• Noise Reduction - Audio processing for cleaner recognition
• Offline Mode - Basic functionality when network unavailable

Architecture

[Microphone] → [VAD Detection] → [Noise Filter] → [Whisper] → [Claude CLI]
                  (Silero)                         (local/remote)     ↓
                                                                   [TTS]
                                                                      ↓
                                                                [Speaker]

Requirements

• Python 3.10+
• Claude CLI installed and configured
• PortAudio library (portaudio19-dev on Ubuntu/Debian)
• Working microphone

Installation

From PyPI

# Basic installation
pip install claudette-voice

# With local Whisper (no server needed)
pip install claudette-voice[local]

# With all optional features
pip install claudette-voice[all]

# Install system dependencies (Ubuntu/Debian)
sudo apt install portaudio19-dev

Optional Extras

Extra	Description	Install Command
local	Local Whisper transcription	pip install claudette-voice[local]
hotkey	Global hotkey support	pip install claudette-voice[hotkey]
system	System info commands	pip install claudette-voice[system]
tray	System tray with waveform	pip install claudette-voice[tray]
notifications	Desktop notifications	pip install claudette-voice[notifications]
audio	Noise reduction	pip install claudette-voice[audio]
all	Everything above + dev tools	pip install claudette-voice[all]

From Source (Development)

# Clone the repository
git clone https://github.com/cyberkoder/claudette.git
cd claudette

# Install system dependencies (Ubuntu/Debian)
sudo apt install portaudio19-dev

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode with all extras
pip install -e ".[all]"

# Copy and configure settings
cp config.yaml.example config.yaml

Configuration

Create a config.yaml file in your working directory:

whisper:
  mode: "local"              # "local" or "remote"
  model: "base"              # tiny, base, small, medium, large-v3
  # url: "http://server:9300/asr"  # For remote mode

wake_word:
  word: "claudette"
  # variants: ["cloud it"]   # Add custom variants for your accent

vad:
  threshold: 0.5
  silence_duration: 1.5
  device: "auto"             # "auto", "cuda", or "cpu"

tts:
  voice: "en-GB-SoniaNeural"
  rate: "+0%"
  pitch: "+0Hz"

memory:
  enabled: true
  max_exchanges: 20

sounds:
  enabled: true
  volume: 0.3

hotkey:
  enabled: true
  # key: "<ctrl>+<shift>+c"  # Customize hotkey

tray:
  enabled: true
  waveform: false            # Floating waveform window

notifications:
  enabled: false

personality:
  preset: "claudette"        # claudette, professional, friendly, butler, pirate

audio_processing:
  noise_reduce: true
  high_pass_cutoff: 80.0
  normalize: true

offline:
  enabled: true

Usage

# Run Claudette
claudette

# Or run as module
python -m claudette

Voice Commands

1. Activate: Say "Claudette" or press Ctrl+Shift+C
2. Command: State your request after "Yes, sir?"
3. Follow-up: Continue without wake word
4. Confirm: Say "yes" or "go ahead" when asked
5. End: Say "thank you" or "goodbye"

Example Interaction

You: "Claudette"
Claudette: "Yes, sir?"

You: "What time is it?"
Claudette: "It's half past 3 in the afternoon, sir."

You: "How's my battery?"
Claudette: "Battery is at 72% with about 3 hours remaining, sir."

You: "Thank you"
Claudette: "My pleasure, sir."

Skills

Claudette includes many built-in skills:

Skill	Trigger Examples
Time	"what time is it", "current time"
Date	"what's the date", "what day is it"
Status	"system status", "how are you"
System Info	"how is my computer", "system info"
Battery	"battery level", "am I plugged in"
Volume	"volume up", "mute", "what's the volume"
Lock Screen	"lock screen", "lock computer"
Screenshot	"take a screenshot"
Voice Change	"list voices", "change voice to libby"
Personality	"list personalities", "change personality to butler"
Clear Memory	"clear memory", "forget everything"
List Skills	"what can you do", "list skills"

Custom Skills

Create custom skills in a skills/ directory:

from claudette import Skill

class WeatherSkill(Skill):
    name = "weather"
    description = "Check the weather"
    triggers = ["what's the weather", "weather forecast"]

    def execute(self, command: str, claudette) -> str:
        # Your implementation here
        return "It's a lovely day, sir."

Project Structure

claudette/
├── src/claudette/
│   ├── __init__.py
│   ├── assistant.py        # Main assistant
│   ├── skills.py           # Skills system
│   ├── sounds.py           # Sound effects
│   ├── hotkey.py           # Hotkey support
│   ├── tray.py             # System tray
│   ├── notifications.py    # Desktop notifications
│   ├── personalities.py    # AI personalities
│   ├── audio_processing.py # Noise reduction
│   └── offline.py          # Offline fallback
├── skills/                  # Custom skills directory
├── config.yaml.example
├── pyproject.toml
└── README.md

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Lint code
ruff check src/

Publishing

For maintainers - publishing to PyPI:

# Build the package
python -m build

# Check the package
twine check dist/*

# Upload to TestPyPI first
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Or use GitHub Releases - creating a release automatically publishes to PyPI.

Troubleshooting

"PortAudio library not found"

# Ubuntu/Debian
sudo apt install portaudio19-dev

# macOS
brew install portaudio

# Fedora
sudo dnf install portaudio-devel

Wake word not detected

• Speak clearly and pause slightly after "Claudette"
• Check logs in logs/ directory
• Add custom variants: say "add wake word cloud" if being misheard

Audio cutting off

• Adjust silence_duration in config.yaml
• Check microphone levels

Support the Project

If you find Claudette useful, consider buying me a coffee!

License

MIT License - see LICENSE for details.

Acknowledgments

• Anthropic for Claude
• Silero for VAD model
• Edge TTS for text-to-speech
• faster-whisper for local transcription
• The 1940s for the aesthetic inspiration

---

"Good day, sir. Claudette at your service."