Raz — Sprachschnittstelle für Claude Code

Sprich mit Claude Code per Stimme. Claude antwortet dir. Alles läuft lokal auf deinem Mac — keine Cloud-APIs, keine Abos, keine Daten verlassen dein Gerät.

Raz (aus dem Aramäischen רָז, „offenbartes Geheimnis") gibt Claude Code eine Stimme und Ohren, mithilfe von kokoro-mlx für die Sprachausgabe und mlx-whisper für das Zuhören, beide optimiert für Apple Silicon.

So funktioniert es

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

Das war's. Wenn Raz aktiv ist, führst du ein Sprachgespräch mit Claude. Codeblöcke und Tabellen werden stillschweigend übersprungen — nur Prosa wird gesprochen.

Was du brauchst

Einrichtung

Die gesamte Einrichtung dauert etwa 5 Minuten. Jeder Schritt ist Copy-Paste.

Schritt 1: Klonen und installieren

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

Das lädt den Code herunter und installiert alle Python-Abhängigkeiten (kokoro-mlx, mlx-whisper, FastAPI, pynput usw.) in einer isolierten virtuellen Umgebung.

Schritt 2: Die CLI installieren

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

Stelle sicher, dass ~/.local/bin in deinem PATH ist. Falls nicht:

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

Überprüfe, ob es funktioniert:

raz help

Schritt 3: Den MCP-Server registrieren

Dadurch kann Claude Code Raz über 10 integrierte Tools steuern (sprechen, Stimme wechseln, Aufnahme starten/stoppen usw.):

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

Schritt 4: Auto-Sprache einrichten

Dieser Hook sorgt dafür, dass Claudes Antworten automatisch laut vorgelesen werden. Füge ihn zu deinen Claude-Code-Einstellungen hinzu:

cat ~/.claude/settings.json

Wenn die Datei existiert, füge den Abschnitt hooks hinzu. Wenn nicht, erstelle sie:

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

Wichtig: Ersetze /FULL/PATH/TO/claude-voice-interaction durch den tatsächlichen Pfad, in den du das Repository geklont hast. Du kannst ihn mit pwd abrufen, während du dich im Projektverzeichnis befindest.

Schritt 5: Erster Start

raz start

Das startet zwei Dinge:

• Den TTS-Server (Text-to-Speech) — lädt das kokoro-mlx-Modell (~10 Sekunden beim ersten Mal)

• Den STT-Daemon (Speech-to-Text) — wartet auf die rechte Optionstaste

Du solltest sehen:

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

Teste es:

raz say "Hello, I can speak now"

Wenn du die Stimme hörst, funktioniert alles. Stoppe Raz mit:

raz stop

Raz verwenden

Eine Sprachsitzung starten

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

Mit Claude sprechen (Push-to-Talk)

1. Halte Rechte Option (⌥) auf deiner Tastatur gedrückt

2. Sprich deine Nachricht

3. Lasse die Taste los

4. Deine Worte werden transkribiert und in Claude Code eingefügt

Du hörst ein Tink-Geräusch, wenn die Aufnahme beginnt, und ein Pop, wenn sie endet.

Beim ersten Mal: macOS fragt nach der Bedienungshilfen-Berechtigung für deine Terminal-App. Erteile sie — pynput benötigt sie, um den Hotkey global zu erkennen.

Beim ersten Drücken: Das Whisper-Modell wird beim ersten Gebrauch geladen (~3 Sekunden). Danach ist die Transkription nahezu sofort. Das Modell wird nach 5 Minuten Inaktivität automatisch entladen, um Speicher freizugeben.

Die Stimme wechseln

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

Geschwindigkeit anpassen

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

Einmalige Transkription

Nimm Audio auf und kopiere die Transkription in deine Zwischenablage (ohne den Daemon):

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

Eine Tastenkombination einrichten (optional)

Raz mit einer globalen Tastenkombination aus jeder App ein- und ausschalten:

raz shortcut install

Weise dann die Tastenkombination zu:

1. Systemeinstellungen → Tastatur → Tastenkürzel → Dienste → Allgemein

2. Finde „Raz aktivieren"

3. Klicke auf „Tastenkürzel hinzufügen" und drücke deine bevorzugte Tastenkombination (z. B. ⌃⌘R)

Jetzt schaltet diese Tastenkombination Raz von überall aus ein und aus, mit einer macOS-Benachrichtigung.

Stimmen

54 Stimmen in 10 Sprachen. Highlights:

Vollständige Liste: raz voices

Konfiguration

Auto-Sprachmodi

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

Spracherkennung

Raz erkennt automatisch, ob Text Spanisch oder Englisch ist, und wechselt entsprechend die Stimme. Wenn du em_alex (spanisch, männlich) einstellst und Claude auf Englisch antwortet, wechselt Raz automatisch für diese Antwort auf am_adam (Englisch, männlich) und dann wieder zurück.

STT-Sprache

Der Push-to-Talk-Daemon ist standardmäßig auf Spanisch eingestellt. Starte ihn mit einer anderen Sprache:

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

Architektur

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

Der STT-Daemon lädt Whisper beim ersten Tastendruck verzögert und entlädt es nach 5 Minuten Inaktivität automatisch, um ~4 GB Speicher freizugeben.

Fehlerbehebung

„Rechte Option bewirkt nichts"

Deine Terminal-App benötigt die Bedienungshilfen-Berechtigung. Gehe zu Systemeinstellungen → Datenschutz & Sicherheit → Bedienungshilfen und füge dein Terminal hinzu (iTerm2, Terminal.app usw.).

„raz start hängt bei 'Whisper-Modell wird geladen'"

Beim ersten Start wird das Whisper-Modell heruntergeladen (~800 MB). Überprüfe deine Internetverbindung. Das Modell wird nach dem ersten Download zwischengespeichert.

„Port 8787 ist bereits belegt"

Eine andere Instanz von Raz läuft. Beende sie:

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

„Daemon lässt sich nicht stoppen"

pkill -f "run_daemon"

„Kein Ton"

Überprüfe, ob die Audioausgabe deines Macs korrekt eingestellt ist (Systemeinstellungen → Sound). Raz spielt über das Standard-Ausgabegerät.

CLI-Referenz

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

Wenn Raz als MCP-Server registriert ist, erhält Claude Code diese 10 Tools:

Lizenz

MIT