Raz — Voice Interface for Claude Code

Talk to Claude Code with your voice. Claude talks back. Everything runs locally on your Mac — no cloud APIs, no subscriptions, no data leaves your machine.

Raz (from Aramaic רָז, "mystery revealed") gives Claude Code a voice and ears using kokoro-mlx for speech and mlx-whisper for listening, both optimized for Apple Silicon.

How It Works

You speak (hold Right Option key) ──► Whisper transcribes ──► text goes to Claude
Claude responds ──► auto-speak reads the response aloud through your speakers

That's it. When Raz is on, you have a voice conversation with Claude. Code blocks and tables are silently skipped — only prose is spoken.

What You Need

Setup

The whole setup takes about 5 minutes. Every step is copy-paste.

Step 1: Clone and install

git clone https://github.com/Mateob6/claude-voice-interaction.git
cd claude-voice-interaction
uv sync

This downloads the code and installs all Python dependencies (kokoro-mlx, mlx-whisper, FastAPI, pynput, etc.) in an isolated virtual environment.

Step 2: Install the CLI

mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/raz" ~/.local/bin/raz
chmod +x scripts/raz scripts/start_server.sh scripts/stop_server.sh

Make sure ~/.local/bin is in your PATH. If it's not:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify it works:

raz help

Step 3: Register the MCP server

This lets Claude Code control Raz through 10 built-in tools (speak, change voice, start/stop listening, etc.):

claude mcp add raz -- uv run --directory "$(pwd)" python -m raz.mcp_server

Step 4: Set up auto-speak

This hook makes Claude's responses automatically spoken aloud. Add it to your Claude Code settings:

cat ~/.claude/settings.json

If the file exists, add the hooks section. If it doesn't, create it:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/FULL/PATH/TO/claude-voice-interaction/hooks/stop_hook.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Important: Replace /FULL/PATH/TO/claude-voice-interaction with the actual path where you cloned the repo. You can get it with pwd while inside the project directory.

Step 5: First run

raz start

This starts two things:

• The TTS server (text-to-speech) — loads the kokoro-mlx model (~10 seconds first time)

• The STT daemon (speech-to-text) — listens for the Right Option key

You should see:

=== Starting Raz ===
Starting Raz TTS server (background) on port 8787...
Raz ready!
Starting STT daemon (lang=es)...
Loading Whisper model. ready!
PID: 12345

Test it:

raz say "Hello, I can speak now"

If you hear the voice, everything is working. Stop Raz with:

raz stop

Using Raz

Start a voice session

raz start    # start voice + mic
raz stop     # stop everything
raz status   # check what's running

Talk to Claude (push-to-talk)

1. Hold Right Option (⌥) on your keyboard

2. Speak your message

3. Release the key

4. Your words are transcribed and pasted into Claude Code

You'll hear a Tink sound when recording starts and a Pop when it stops.

First time: macOS will ask for Accessibility permission for your terminal app. Grant it — pynput needs it to detect the hotkey globally.

First press: The Whisper model loads on first use (~3 seconds). After that, transcription is near-instant. The model auto-unloads after 5 minutes of idle to free memory.

Change the voice

raz voice af_heart    # switch to English female (best quality)
raz voice em_alex     # switch to Spanish male (default)
raz voice bm_fable    # switch to British storyteller
raz voices            # see all 54 voices

Adjust speed

raz speed 1.5    # faster
raz speed 0.8    # slower
raz speed 1.0    # normal

One-shot transcription

Record audio and copy the transcription to your clipboard (without the daemon):

raz listen         # Spanish (default)
raz listen en      # English
# Press Ctrl+C when done speaking

Set up a keyboard shortcut (optional)

Toggle Raz on/off from any app with a global keyboard shortcut:

raz shortcut install

Then assign the shortcut:

1. System Settings → Keyboard → Keyboard Shortcuts → Services → General

2. Find "Activar Raz"

3. Click "Add Shortcut" and press your preferred key combo (e.g., ⌃⌘R)

Now that key combo toggles Raz on/off from anywhere, with a macOS notification.

Voices

54 voices across 10 languages. Highlights:

Full list: raz voices

Configuration

Auto-speak modes

raz mode smart    # recommended
raz mode auto     # hear everything
raz mode off      # silent, use speak() when needed

Language detection

Raz auto-detects whether text is Spanish or English and switches voices accordingly. If you set em_alex (Spanish male) and Claude responds in English, Raz automatically switches to am_adam (English male) for that response, then back.

STT language

The push-to-talk daemon defaults to Spanish. Start it with a different language:

raz stt start en    # English
raz stt start es    # Spanish (default)

Architecture

Claude Code
  ├── MCP tools (10) ──► localhost:8787 (TTS: kokoro-mlx)
  │                  ──► raz.stt.daemon  (STT: control)
  ├── Stop hook ──► localhost:8787/auto-speak
  ├── STT daemon (pynput + mlx-whisper) ──► clipboard ──► paste
  └── CLI (raz) ──► unified lifecycle

The STT daemon lazy-loads Whisper on first keypress and auto-unloads after 5 minutes of idle to free ~4 GB of memory.

Troubleshooting

"Right Option doesn't do anything"

Your terminal app needs Accessibility permission. Go to System Settings → Privacy & Security → Accessibility, and add your terminal (iTerm2, Terminal.app, etc.).

"raz start hangs on 'Loading Whisper model'"

First run downloads the Whisper model (~800 MB). Check your internet connection. The model is cached after the first download.

"Port 8787 already in use"

Another instance of Raz is running. Kill it:

raz stop
# If that doesn't work:
pkill -f "raz.tts_server"

"Daemon won't stop"

pkill -f "run_daemon"

"No sound output"

Check that your Mac's audio output is set correctly (System Settings → Sound). Raz plays through the default output device.

CLI Reference

raz start           # Start Raz (voice + mic)
raz stop            # Stop Raz
raz on / raz off    # Enable/disable Raz
raz status          # Show Raz status

raz say "text"      # Speak text
raz listen [lang]   # Record → transcribe → clipboard
raz voice NAME      # Change voice
raz voices          # List all 54 voices
raz mode MODE       # smart | auto | off
raz speed N         # 0.5–2.0

raz stt start|stop  # Mic only
raz tts start|stop  # Voice only
raz shortcut install|remove  # Keyboard shortcut

MCP Tools

When registered as an MCP server, Claude Code gets these 10 tools:

License

MIT