Modo de voz (Voice): habla tus instrucciones en lugar de escribirlas

📚 Navegación de la serie: El artículo anterior 46 Configuración de desarrollo detalló cómo estructurar el entorno para que Claude Code trabaje en tu máquina. Este artículo aborda una interacción cotidiana: cómo hablar tus instrucciones en lugar de escribirlas en el teclado, traduciéndolas a texto en tiempo real. Con /voice activado, puedes mantener presionada la barra espaciadora para hablar y la transcripción aparecerá en el cuadro de entrada, permitiéndote combinar voz y escritura. Aunque parece simple, existen requisitos de acceso y compatibilidad que debes conocer para no atascarte en el primer paso.

⚠️ Funcionalidad experimental sujeta a cambios. Los comandos, parámetros y versiones descritos se basan en la especificación oficial, pero la transcripción de voz está en desarrollo continuo; el comportamiento podría variar en tu entorno, por lo que debes verificar los mensajes reales del comando /voice en tu máquina.

Se suele decir que hablar es más rápido que escribir, pero para los programadores, la entrada de voz tradicional no ha sido del todo efectiva. Escribimos rápido y usamos nombres de variables, funciones o nomenclaturas como snake_case que los motores de voz genéricos suelen transcribir con errores, requiriendo más tiempo para corregirlos que haberlos escrito desde el principio. Al intentar documentar código con herramientas de voz genéricas, términos como useEffect suelen transcribirse como palabras separadas inconexas, lo que termina en el desuso de la herramienta.

Sin embargo, la transcripción de voz de Claude Code ofrece dos características que cambian esta experiencia: primero, está optimizada para vocabulario de programación, reconociendo términos como regex, OAuth, JSON o localhost; segundo, incluye el nombre de tu proyecto y la rama actual de git como contexto de reconocimiento, lo que incrementa la precisión al transcribir la jerga técnica de tu código base en comparación con herramientas genéricas.

Su objetivo no es que dictes código línea por línea, sino ahorrarte la redacción de descripciones extensas de requerimientos. Decir "refactoriza el middleware de autenticación para usar el nuevo ayudante de validación de tokens" en voz alta es más rápido que escribirlo carácter por carácter en el teclado. En este artículo aprenderás a configurarlo, usarlo con fluidez y resolver los inconvenientes habituales de acceso.

Al terminar este artículo, obtendrás:

• Una explicación simple de qué es la transcripción de voz y dónde se procesa (fuera de tu máquina local).
• La regla de acceso principal: requiere autenticación con cuenta de Claude.ai; no funcionará si usas una API key de forma directa.
• Una tabla de soporte por plataforma (macOS, Windows, Linux, WSL, entornos remotos y VS Code).
• Cómo utilizar los dos modos de grabación (mantener presionado vs. pulsar una vez) y para qué escenarios es adecuado cada uno.
• Cómo configurarlo por defecto al iniciar, modificar el idioma de transcripción y cambiar la tecla de activación.
• Un ejercicio práctico paso a paso para activarlo y realizar tu primera instrucción por voz.

---

01 Concepto: qué es la transcripción de voz y dónde se procesa

Para empezar, la conclusión: la transcripción de voz captura tu audio, lo traduce a texto y lo introduce directamente en el cuadro de entrada de la sesión. No se trata de una conversación hablada bidireccional con Claude, sino de reemplazar la escritura del teclado por tu voz.

Analogía: transcripción en tiempo real en una reunión. Al activar los subtítulos automáticos en una videollamada, el sistema traduce tus palabras en texto en la parte inferior de la pantalla a medida que hablas. El sistema no conversa contigo, solo transcribe tu audio a formato escrito. La función de voz en Claude Code actúa de esta manera: mantienes presionada la tecla para hablar, el audio se traduce a texto en el cuadro de entrada, y el texto resultante se procesa exactamente igual que si lo hubieras escrito. Puedes editar el texto resultante en el teclado para agregar detalles antes de presionar enter.

La descripción oficial es directa:

Diga sus instrucciones en la CLI de Claude Code en lugar de escribirlas. Su voz se transcribe en tiempo real en la entrada de instrucciones, lo que le permite combinar voz y escritura en el mismo mensaje.

Esta capacidad de combinar voz y escritura es muy útil: el texto transcrito se posiciona donde se encuentra tu cursor, dejándolo al final de la frase. Esto te permite describir la tarea general con tu voz y añadir con el teclado un nombre exacto de archivo o una ruta específica.

Ten en cuenta el siguiente punto, que define el acceso al servicio: el procesamiento de audio no se realiza en tu máquina local. La documentación oficial lo indica:

La transcripción de voz envía tu flujo de audio a los servidores de Anthropic para su procesamiento. El audio no se procesa localmente.

El procesamiento remoto implica tres condiciones que detallaremos en la siguiente sección: primero, requiere conexión a internet activa; segundo, requiere iniciar sesión con una cuenta de Claude.ai (para validar el usuario en el servidor); y tercero, no está disponible en entornos de red remotos sin acceso a micrófonos locales.

Por último, un detalle a tener en cuenta: la transcripción de voz es gratuita y no consume tu cuota de mensajes. La documentación oficial confirma:

Las transcripciones de voz no consumen mensajes ni tokens de Claude, ni se contabilizan en los límites de consumo del comando /usage.

Esto significa que dictar instrucciones extensas no afectará tu cuota de suscripción (la facturación se detalló en el artículo 06). Puedes validar esto consultando el consumo con /usage antes y después de dictar instrucciones; verás que la cuota se mantiene intacta. La transcripción y el consumo de tokens del modelo son flujos independientes.

💡 Resumen rápido: La transcripción de voz traduce tu voz en texto en el cuadro de entrada, permitiéndote complementar la redacción con el teclado. El procesamiento de audio se realiza en los servidores de Anthropic, y la transcripción no consume tokens ni afecta tu cuota de /usage.

---

02 Requisito de cuenta: requiere inicio de sesión con cuenta de Claude.ai

Esta es la restricción principal del servicio. Muchos fallos de activación se deben al tipo de cuenta configurada en la sesión.

Dado que el procesamiento del audio se realiza en los servidores de Anthropic, la transcripción de voz requiere que estés autenticado con una cuenta de usuario de Claude.ai. La documentación oficial detalla las limitaciones:

La transcripción de voz solo está disponible si te has autenticado con una cuenta de Claude.ai, y no se encuentra disponible si Claude Code está configurado con una clave de API directa de Anthropic, Amazon Bedrock, Google Vertex AI o Microsoft Foundry. Tampoco está disponible si tu organización tiene habilitado el cumplimiento de HIPAA.

Es decir, según tu tipo de acceso (visto en los artículos 04 y 05):

• Suscripción activa (Pro / Max de cuenta Claude.ai): ✅ Soporta la función de voz.
• Clave de API directa de Anthropic: ❌ No disponible.
• Proveedores de nube (Bedrock, Vertex, Foundry): ❌ No disponible.
• Cuentas corporativas con HIPAA: ❌ No disponible.

Esta limitación se debe a que el servicio de transcripción está integrado en la infraestructura de cuentas de usuario de Claude.ai, y no en los canales de API directa.

Si intentas activar /voice utilizando un acceso por API key, el sistema mostrará la alerta:

Voice mode requires a Claude.ai account

Si experimentas este error, el origen es tu método de autenticación. La solución es ejecutar /login para autenticarte con tu cuenta de suscripción de Claude.ai. Si usas la máquina con una API key de la empresa, la función de voz no estará disponible hasta que cambies de método de acceso.

Método de acceso (Artículos 04-05)	¿Soporta transcripción de voz?
Cuenta de Claude.ai (Planes Pro / Max)	✅ Sí
API key directa de Anthropic	❌ No (Muestra la alerta requires a Claude.ai account)
Proveedores externos (Bedrock, Vertex, Foundry)	❌ No
Cumplimiento de HIPAA activo	❌ No

💡 Resumen rápido: La función de voz solo está disponible bajo sesiones de cuenta de Claude.ai. Los accesos directos por API key, integraciones de nube como Bedrock o Vertex, o cuentas corporativas con HIPAA no la soportan y mostrarán la alerta requires a Claude.ai account.

---

03 Soporte por plataforma y acceso al hardware de micrófono

Además del tipo de cuenta, el servicio requiere aceso físico al micrófono de la máquina. Esto restringe el uso según la plataforma y el tipo de entorno (local o remoto).

La transcripción de voz requiere acceso al micrófono local, por lo que no es compatible con entornos remotos donde el proceso se ejecuta fuera de tu máquina principal, como sesiones SSH o la versión web del agente.

La documentación oficial aclara esta restricción:

La transcripción de voz requiere acceso al micrófono local, por lo que no funciona en entornos remotos como Claude Code en web o a través de sesiones SSH.

Detallamos la compatibilidad según la plataforma en la siguiente tabla:

Entorno de ejecución	Compatibilidad	Detalles de configuración
macOS	✅ Soportado	Solicita confirmación de acceso al micrófono del sistema al iniciar /voice
Windows	✅ Soportado	Asegúrate de habilitar el permiso de micrófono para la aplicación de terminal en la configuración de Windows
Linux	✅ Soportado	Utiliza la integración nativa; si falla, recurre a herramientas del sistema como arecord o rec
WSL	⚠️ Parcial	Requiere WSLg para procesar audio en WSL2; no es compatible con WSL1
Sesiones SSH	❌ No soportado	El proceso se ejecuta en la máquina remota y no tiene acceso al hardware local
Claude Code en web	❌ No soportado	Ejecución remota sin acceso al canal de micrófono local (Artículo 11)
Extensión de VS Code	✅ Soportado	Compatible bajo entornos locales; ❌ no compatible en VS Code Remote (SSH / Dev Containers / Codespaces)

Puntos de atención específicos:

• Entornos remotos: En sesiones SSH, contenedores en la nube o extensiones remotas de VS Code, el proceso de Claude Code se ejecuta en un servidor remoto mientras tu micrófono físico está en tu máquina local. Debido a esto, la captura de audio no es posible y la función de voz estará desactivada.
• Entorno WSL: Requiere WSLg (la arquitectura gráfica y de audio de WSL2) disponible en las versiones de WSL instaladas desde la tienda de Microsoft en Windows 10 y 11. Si utilizas WSL1, la captura de audio no es compatible; se recomienda ejecutar Claude Code de forma nativa en la terminal de Windows.
• Dependencias en Linux: Si tu sistema Linux no cuenta con las herramientas de audio necesarias, al iniciar /voice la consola mostrará el comando de instalación correspondiente para tu distribución (como sudo apt-get install sox), facilitando su configuración.

💡 Resumen rápido: La captura de audio requiere un micrófono local. Es compatible en ejecuciones locales de Mac, Windows y Linux, pero no está soportada en sesiones remota de SSH, la versión web del agente o VS Code Remote. WSL requiere el soporte de audio de WSLg.

---

04 Modos de grabación: mantener presionado vs. pulsar una vez

Al activar /voice, puedes seleccionar entre dos modos de interacción con el micrófono según tus preferencias de uso.

Analogía: transmisor de radio (Walkie-talkie) vs. grabadora de mano. El transmisor requiere mantener presionado el botón para hablar y transmitir, cortando la comunicación al soltarlo (modo "hold"); la grabadora requiere un clic para iniciar y otro para detener, sin necesidad de sostener el botón durante el dictado (modo "tap").

Comparamos las características de ambos modos:

Característica	Modo hold (mantener presionado) - Por defecto	Modo tap (pulsar una vez)
Activación	Mantener presionada la barra espaciadora	Pulsar una vez la barra espaciadora
Finalización	Soltar la barra espaciadora	Pulsar de nuevo la barra espaciadora
Envío de mensaje	Requiere presionar Enter (configurable para envío automático)	Envía el mensaje automáticamente al detener si tiene al menos 3 palabras
Uso recomendado	Para dictados cortos, interrupciones rápidas o añadir frases puntuales	Para descripciones extensas o dictados continuos sin sostener la tecla

Modo hold (Por defecto): interacción por pulsación continua

Es el método predeterminado al activar /voice. Mantienes presionada la barra espaciadora para grabar y la sueltas para finalizar.

Ten en cuenta que este modo tiene una fase breve de inicio (warm-up). El sistema detecta la repetición de pulsación de teclas en la terminal para identificar que mantienes la tecla presionada. Verás un mensaje keep holding... en la línea de estado antes de mostrar el indicador visual de audio. La documentación oficial lo describe:

Los primeros caracteres de repetición de tecla introducidos en el inicio se limpian automáticamente al activarse la grabación. Una pulsación rápida de la barra espaciadora se procesa como un espacio normal en el editor, ya que el detector de pulsación continua requiere una secuencia rápida de repeticiones para activarse.

En resumen: pulsar la barra espaciadora de forma normal sigue insertando un espacio de texto; solo si la mantienes presionada se activa la grabación de audio.

Al hablar, el texto traducido aparecerá en tiempo real en la consola. Al soltar la tecla, el texto se inserta en la posición del cursor de tu editor.

> refactor the auth middleware to ▮
  # Mantienes presionado Space y dictas "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

De forma predeterminada, el mensaje no se envía automáticamente al soltar la tecla, permitiéndote revisar el texto resultante o añadir detalles con el teclado. Si prefieres que se envíe directamente al soltar la tecla, puedes activar la opción autoSubmit en la configuración (explicado en la siguiente sección).

Modo tap: interacción por clics de inicio y parada

Este modo utiliza clics sencillos para iniciar y detener la grabación. Habilítalo usando /voice tap.

Este modo requiere una versión de software más reciente en comparación con el modo hold. La documentación oficial indica las versiones requeridas:

La transcripción de voz requiere Claude Code v2.1.69 o superior. El modo tap requiere la versión v2.1.116 o superior.

Verifica tu versión con claude --version si experimentas problemas al iniciar el modo tap.

Detalles de usabilidad del modo tap:

• La pulsación inicial solo inicia la grabación si el cuadro de entrada está vacío, evitando activaciones accidentales al escribir texto con la barra espaciadora.
• Si la transcripción resultante contiene menos de tres palabras al detener la grabación, se inserta en el editor pero no se envía de forma automática, previniendo envíos accidentales por ruidos de fondo.
• Cuenta con apagado automático si detecta 15 segundos de silencio o si la grabación alcanza un límite de dos minutos.

El modo tap suele ser la opción preferida para dictar requerimientos extensos, ya que no requiere sostener la tecla; el modo hold es útil para inserciones rápidas y correcciones puntuales en la terminal.

💡 Resumen rápido: El modo hold (por defecto) requiere mantener presionada la barra espaciadora para grabar; el modo tap (requiere v2.1.116+) utiliza pulsaciones sencillas para iniciar y detener, enviando el mensaje automáticamente al finalizar.

---

05 Opciones de configuración: persistencia, idioma y atajos de teclado

Puedes ajustar el comportamiento del servicio a tus preferencias modificando el archivo de configuración.

1. Activar la función de voz por defecto

Si deseas que la función de voz esté disponible de forma automática al iniciar una sesión sin tener que escribir /voice, agrégala en el campo voice de tu archivo de configuración global settings.json:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

Define la opción enabled en true y el modo deseado (hold o tap) en mode.

Para activar el envío automático al soltar la tecla en el modo hold, añade la opción autoSubmit:

{
  "voice": {
    "enabled": true,
    "mode": "hold",
    "autoSubmit": true
  }
}

Esto enviará la instrucción de forma automática si la transcripción procesa al menos tres palabras.

2. Modificar el idioma de transcripción

La función de voz utiliza el idioma de la configuración global de la sesión. De forma predeterminada, está configurado en inglés. Si dictas en español sin cambiar esta configuración, la transcripción no procesará las palabras correctamente.

Ten en cuenta los idiomas soportados oficialmente por el servicio de transcripción de voz:

El servicio de transcripción soporta actualmente: checo, danés, holandés, inglés, francés, alemán, griego, hindi, indonesio, italiano, japonés, coreano, noruego, polaco, portugués, ruso, español, sueco, turco y ucraniano.

El español está soportado de forma oficial. Para cambiar el idioma de la sesión al español, edita el campo language en la configuración general de Claude Code, usando el nombre del idioma o su código BCP 47:

{
  "language": "es"
}

Esto configurará el procesamiento de voz en español. La documentación oficial aclara que si configuras un idioma no soportado por el servicio de voz, la CLI mostrará una advertencia al iniciar /voice y revertirá el reconocimiento de voz al inglés, sin alterar el idioma de respuesta de texto de Claude.

3. Modificar la tecla de activación

La tecla de activación por defecto es la barra espaciadora (Space). Si deseas cambiarla por otra tecla o combinación, edita la asignación para voice:pushToTalk en tu archivo de atajos de teclado ~/.claude/keybindings.json (la estructura se explicó en el artículo 14):

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

Advertencia para la asignación de teclas en el modo hold:

En el modo hold, evite asignar la función a teclas de una sola letra (como 'v'), ya que el inicio de grabación depende del retraso de repetición de teclas y la letra se escribirá en el cuadro de entrada antes de iniciarse la grabación.

Se recomienda utilizar combinaciones de teclas con modificadores (como meta+k o ctrl+k) para el modo hold; al presionar la combinación, la grabación se inicia de forma inmediata sin insertar caracteres adicionales. El modo tap no tiene fase de warm-up, por lo que admite asignaciones más flexibles.

💡 Resumen rápido: Configura la persistencia en settings.json mediante voice.enabled y voice.mode. El español está soportado oficialmente; configúralo en el campo language de la sesión. Cambia la tecla de activación asignando voice:pushToTalk en keybindings.json y evita letras simples en el modo hold.

---

06 Ejercicio práctico: activar la voz y realizar tu primera transcripción

Realizaremos un ejercicio básico de validación: confirmar los requisitos de versión, activar el micrófono, grabar una frase corta y enviarla en la sesión.

Requisitos: Sesión iniciada con cuenta de Claude.ai en tu máquina local, micrófono funcional y versión compatible. El proceso requiere conexión a internet activa.

Paso 1: Confirmar la versión de Claude Code (en tu terminal local)

claude --version

Resultado esperado: La versión instalada debe ser v2.1.69 o superior (v2.1.116 o superior si deseas validar el modo tap). De ser necesario, actualiza tu cliente antes de continuar.

Paso 2: Iniciar la función de voz en la conversación

En tu sesión de claude, escribe:

/voice

Resultado esperado: El sistema de terminal o el sistema operativo mostrará una alerta de solicitud de permisos para acceder al micrófono; selecciona permitir. Al completarse la autorización, la línea de estado mostrará un mensaje confirmando la activación de la voz, el modo y el idioma:

Voice mode enabled (hold). Hold Space to record. Dictation language: es (/config to change).

Si el idioma reportado no es el español, puedes configurarlo ejecutando /config y cambiando la opción de idioma. Si experimentas el error Voice mode requires a Claude.ai account, deberás cerrar la sesión con /logout e iniciar con tu cuenta de suscripción usando /login.

Paso 3: Validar el indicador visual

Verifica que en la parte inferior del editor aparezca el mensaje de estado hold Space to speak, indicando que la tecla de grabación está lista.

Paso 4: Realizar la grabación de prueba

Mantén presionada la barra espaciadora (Space). Tras mostrar brevemente el texto de inicio keep holding..., aparecerá el indicador visual de captura de audio. Habla con claridad al micrófono dictando una instrucción simple en español:

# Mantén presionado Space y dicta: lista los archivos de este directorio

Resultado esperado: A medida que hablas, las palabras traducidas aparecerán en el cuadro de entrada de la consola. Al soltar la barra espaciadora, el texto se fijará en el editor:

> lista los archivos de este directorio▮

Ver el texto correspondiente en el editor valida que la transcripción funciona correctamente. El mensaje no se enviará de forma automática en este paso.

Paso 5: Complementar la instrucción con el teclado y enviar

Utilizando el teclado, añade una instrucción adicional al texto resultante para validar la combinación de voz y escritura:

> lista los archivos de este directorio e indica sus tamaños▮

Presiona Enter en el teclado para enviar la instrucción consolidada. Claude procesará y responderá a la solicitud de forma habitual.

Paso 6: Desactivar la función de voz

/voice off

Resultado esperado: El mensaje de estado de voz desaparecerá de la consola y la barra espaciadora volverá a comportarse como una tecla de espacio normal.

Haber completado este ejercicio confirma la configuración de tu micrófono local, la cuenta de acceso compatible y el flujo de traducción de audio a texto. El mismo proceso aplica para dictar tus descripciones de tareas cotidianas.

💡 Resumen rápido: El ejercicio de validación consta de seis pasos: verificar la versión con --version → activar /voice autorizando el micrófono → validar el estado hold Space to speak → dictar una frase de prueba manteniendo presionado Space → complementar el texto resultante en el teclado y enviar → desactivar con /voice off.

---

07 Resumen

En este artículo hemos analizado la función de transcripción de voz de Claude Code, que permite traducir tus palabras a texto en el cuadro de entrada para agilizar la redacción de instrucciones.

Repasemos las características principales:

Concepto	Detalle de la función	Clave de uso
Propósito del servicio	Entrada de texto mediante voz	Traduce el audio en texto del editor; no consume tokens ni afecta tu cuota de /usage
Requisito de cuenta	Autenticación con Claude.ai	Solo compatible con cuentas de suscripción de Claude.ai; no admite claves de API
Soporte de hardware	Acceso a micrófono local	Requiere micrófono local en Mac, Windows o Linux; no compatible bajo SSH o web
Modos de captura	hold (mantener) / tap (pulsar)	hold requiere presionar la tecla para grabar; tap utiliza clics para inicio y parada
Idiomas y teclas	Configuración en settings.json	El español está soportado y se activa configurando language: "es"; la tecla se reasigna con voice:pushToTalk

Ahora puedes:

• Entender el funcionamiento técnico de la transcripción de voz y que se procesa en los servidores de Anthropic.
• Confirmar si tu cuenta de acceso soporta la función de voz o requiere cambiar el método de autenticación.
• Validar la compatibilidad del micrófono según el entorno de ejecución local o remoto.
• Operar la grabación utilizando el modo continuo (hold) o el modo de clics alternados (tap).
• Configurar el español como idioma de reconocimiento y reasignar las teclas de control en settings.json.

El modo de voz complementa tu entorno de programación, permitiéndote describir tareas extensas de manera hablada mientras mantienes el control de edición fino en el teclado.

---

El siguiente artículo es el 48 "Proyecto integrador: unificando el conocimiento". Hemos analizado los componentes, herramientas de red, automatizaciones y modos de control de Claude Code. En la próxima sección consolidaremos lo aprendido en un caso de desarrollo real: crear un proyecto desde cero, configurar sus directrices de desarrollo, estructurar los agentes de apoyo y desplegar la solución, integrando las herramientas en un flujo de trabajo consolidado de principio a fin.

---

Lecturas recomendadas

• Atajos de teclado e interfaz de usuario
• Habilidades del agente (Agent Skills): ampliando capacidades
• Subagentes (Subagents): delegando subtareas