Raz — Interfaz de voz para Claude Code

Habla con Claude Code con tu voz. Claude te responde. Todo se ejecuta localmente en tu Mac: sin APIs en la nube, sin suscripciones, sin que los datos salgan de tu máquina.

Raz (del arameo רָז, "misterio revelado") le da a Claude Code voz y oídos usando kokoro-mlx para el habla y mlx-whisper para escuchar, ambos optimizados para Apple Silicon.

Cómo funciona

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

Eso es todo. Cuando Raz está activo, tienes una conversación por voz con Claude. Los bloques de código y las tablas se omiten silenciosamente: solo se habla la prosa.

Lo que necesitas

Configuración

Toda la configuración toma unos 5 minutos. Cada paso es copiar y pegar.

Paso 1: Clonar e instalar

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

Esto descarga el código e instala todas las dependencias de Python (kokoro-mlx, mlx-whisper, FastAPI, pynput, etc.) en un entorno virtual aislado.

Paso 2: Instalar la 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

Asegúrate de que ~/.local/bin esté en tu PATH. Si no lo está:

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

Verifica que funciona:

raz help

Paso 3: Registrar el servidor MCP

Esto permite que Claude Code controle Raz a través de 10 herramientas integradas (hablar, cambiar voz, iniciar/detener escucha, etc.):

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

Paso 4: Configurar el habla automática

Este hook hace que las respuestas de Claude se hablen automáticamente en voz alta. Añádelo a tu configuración de Claude Code:

cat ~/.claude/settings.json

Si el archivo existe, añade la sección hooks. Si no existe, créalo:

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

Importante: Reemplaza /FULL/PATH/TO/claude-voice-interaction con la ruta real donde clonaste el repositorio. Puedes obtenerla con pwd dentro del directorio del proyecto.

Paso 5: Primera ejecución

raz start

Esto inicia dos cosas:

• El servidor TTS (texto a voz) — carga el modelo kokoro-mlx (~10 segundos la primera vez)

• El demonio STT (voz a texto) — escucha la tecla Opción derecha

Deberías ver:

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

Pruébalo:

raz say "Hello, I can speak now"

Si escuchas la voz, todo funciona. Detén Raz con:

raz stop

Usar Raz

Iniciar una sesión de voz

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

Hablar con Claude (pulsar para hablar)

1. Mantén presionada la Opción derecha (⌥) en tu teclado

2. Habla tu mensaje

3. Suelta la tecla

4. Tus palabras se transcriben y se pegan en Claude Code

Escucharás un sonido Tink cuando comience la grabación y un Pop cuando se detenga.

Primera vez: macOS pedirá permiso de Accesibilidad para tu aplicación de terminal. Concédelo: pynput lo necesita para detectar la tecla de acceso rápido globalmente.

Primera pulsación: El modelo Whisper se carga en el primer uso (~3 segundos). Después, la transcripción es casi instantánea. El modelo se descarga automáticamente después de 5 minutos de inactividad para liberar memoria.

Cambiar la voz

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

Ajustar velocidad

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

Transcripción de una sola vez

Graba audio y copia la transcripción a tu portapapeles (sin el demonio):

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

Configurar un atajo de teclado (opcional)

Activa/desactiva Raz desde cualquier aplicación con un atajo de teclado global:

raz shortcut install

Luego asigna el atajo:

1. Configuración del sistema → Teclado → Atajos de teclado → Servicios → General

2. Busca "Activar Raz"

3. Haz clic en "Añadir atajo" y presiona la combinación de teclas que prefieras (por ejemplo, ⌃⌘R)

Ahora esa combinación de teclas activa/desactiva Raz desde cualquier lugar, con una notificación de macOS.

Voces

54 voces en 10 idiomas. Destacados:

Lista completa: raz voices

Configuración

Modos de habla automática

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

Detección de idioma

Raz detecta automáticamente si el texto es español o inglés y cambia las voces en consecuencia. Si configuras em_alex (masculino español) y Claude responde en inglés, Raz cambia automáticamente a am_adam (masculino inglés) para esa respuesta, y luego vuelve.

Idioma de STT

El demonio de pulsar para hablar usa español por defecto. Inícialo con un idioma diferente:

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

Arquitectura

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

El demonio STT carga Whisper de forma diferida en la primera pulsación de tecla y se descarga automáticamente después de 5 minutos de inactividad para liberar ~4 GB de memoria.

Solución de problemas

"La Opción derecha no hace nada"

Tu aplicación de terminal necesita permiso de Accesibilidad. Ve a Configuración del sistema → Privacidad y seguridad → Accesibilidad, y añade tu terminal (iTerm2, Terminal.app, etc.).

"raz start se cuelga en 'Cargando modelo Whisper'"

La primera ejecución descarga el modelo Whisper (~800 MB). Comprueba tu conexión a internet. El modelo se guarda en caché después de la primera descarga.

"El puerto 8787 ya está en uso"

Otra instancia de Raz está en ejecución. Mátala:

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

"El demonio no se detiene"

pkill -f "run_daemon"

"No hay salida de sonido"

Comprueba que la salida de audio de tu Mac esté configurada correctamente (Configuración del sistema → Sonido). Raz reproduce a través del dispositivo de salida predeterminado.

Referencia de CLI

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

Herramientas MCP

Cuando se registra como servidor MCP, Claude Code obtiene estas 10 herramientas:

Licencia

MIT