cortana-tts

A standalone, pip-installable local TTS server with ready-made integrations for Claude Code, OpenCode, and GitHub Copilot CLI.

Speaks assistant responses aloud in real time using a fast, on-device neural TTS model — no cloud, no API keys.

Requirements

Linux also requires PortAudio:

sudo apt install libportaudio2   # Debian/Ubuntu
sudo pacman -S portaudio          # Arch
brew install portaudio            # macOS (if not auto-bundled)

Windows requires the Visual C++ Redistributable.

Install

pip install cortana-tts

Engine options

The setup wizard will ask which you prefer on first run. You can also switch at any time:

cortana-tts engine                    # show current engine
cortana-tts engine standard           # switch to standard (kokoro)
cortana-tts engine lightweight        # switch to lightweight (piper-tts)
cortana-tts engine lightweight en_US-ryan-medium  # switch with specific voice

Available lightweight voices: en_US-lessac-medium, en_US-ryan-medium, en_US-amy-medium, en_GB-alba-medium, en_GB-northern_english_male-medium

Quick start

# Start the server (foreground)
cortana-tts start

# Start in background
cortana-tts start --bg

# Test speech
cortana-tts speak "Hello. The server is running."

# Check status
cortana-tts status

# Stop background server
cortana-tts stop

The server listens on http://127.0.0.1:5111 by default.

Integrations

Claude Code

Installs notify.sh (or .ps1 on Windows) and status.sh into ~/.config/cortana-tts/hooks/, then registers them as Claude Code hooks in ~/.claude/settings.json.

cortana-tts install claude

Claude Code must be restarted to pick up the new hooks. After that, every response containing a <!-- <tts>...</tts> --> tag will be spoken aloud automatically.

Uninstall:

cortana-tts uninstall claude

OpenCode

Copies integrations/opencode/index.ts to ~/.config/opencode/plugins/cortana-tts.ts and registers it in ~/.config/opencode/opencode.json.

cortana-tts install opencode

Uninstall:

cortana-tts uninstall opencode

GitHub Copilot CLI

Appends a shell function to ~/.zshrc and ~/.bashrc (or PowerShell profile on Windows) that wraps gh copilot and speaks the response.

cortana-tts install copilot
source ~/.zshrc   # or restart your shell

Uninstall:

cortana-tts uninstall copilot

Voices

22 voices are available. Switch at any time — the new voice takes effect immediately.

cortana-tts voice list
cortana-tts voice set af_heart

Configuration

Config is read from ~/.config/cortana-tts/.env (or the path in $CORTANA_TTS_CONFIG).

Copy the example and edit:

cp .env.example ~/.config/cortana-tts/.env

Key settings:

API endpoints

The server exposes these HTTP endpoints:

TTS tag format

For Claude Code integration, responses should include a hidden TTS summary:

<!-- <tts>Your spoken summary here.</tts> -->
<!-- <tts mood="error">Something went wrong.</tts> -->

Valid moods: error, success, warn, melancholy (omit for default).

Platform notes

Linux: Requires libportaudio2. Install with sudo apt install libportaudio2.

macOS: PortAudio is bundled with sounddevice wheels. No extra steps needed.

Windows: Requires Visual C++ Redistributable 2015–2022. Hook scripts use PowerShell (.ps1). The cortana-tts install claude command automatically selects the correct scripts.

PID file location

CLI reference

cortana-tts start [--port 5111] [--voice af_heart] [--bg]
cortana-tts stop
cortana-tts restart
cortana-tts status
cortana-tts voice list
cortana-tts voice set <name>
cortana-tts speak "<text>"
cortana-tts engine
cortana-tts engine standard
cortana-tts engine lightweight [voice]
cortana-tts install claude|opencode|copilot
cortana-tts uninstall claude|opencode|copilot