🎙️ VoxAgent

Habla con tu agente de programación. Te responde.

I/O de voz local-first para Claude Code, Cursor, OpenClaw y cualquier cliente MCP.

English · 简体中文

Por qué

Los agentes de programación pasaron de autocompletado a compañeros de trabajo, pero la interfaz sigue siendo un teclado. VoxAgent le da a tu agente oídos y boca:

• 🎤 listen() — dicta instrucciones, fragmentos de código o comentarios de revisión de código

• 🔊 speak() — actualizaciones de progreso habladas; ve a por un café mientras tu agente habla

• 🗣️ ask_user() — el agente pregunta, tú respondes en voz alta desde el otro lado de la habitación

• 🕹️ Push-to-talk — mantén pulsada una tecla de acceso rápido global en cualquier lugar; tus palabras van directamente a claude -p, y la respuesta se habla en voz alta

Todo se ejecuta en tu máquina. El STT es totalmente offline (faster-whisper); el TTS comienza con una voz sin configuración y mejora a un servidor CosyVoice local para obtener voz de calidad de producción. No se requieren claves de API.

Inicio rápido

pip install 'voxagent[local]'
voxagent doctor        # check mic + deps
voxagent demo          # try the talk-loop standalone

# Register with Claude Code
claude mcp add voxagent -- voxagent serve

# Enable the agent skill (when to speak, how to behave)
mkdir -p ~/.claude/skills && cp -r skills/voice-control ~/.claude/skills/

# Push-to-talk daemon (optional): talk to Claude Code from any app
pip install 'voxagent[ptt]'
voxagent ptt --send 'claude -p'

Luego simplemente di: "voice mode on" — o mantén pulsada la tecla de acceso rápido PTT (por defecto Ctrl+Shift+Space) y habla.

Funciona con cualquier cliente MCP: Cursor, OpenClaw, Codex y compañía hablan MCP.

Arquitectura

        ┌─────────────┐     MCP (stdio)      ┌──────────────────┐
 mic ──▶│   listen()  │◀────────────────────▶│  Claude Code /   │
        │  (STT)      │                      │  Cursor / any    │
 spk ◀──│   speak()   │◀────────────────────▶│  MCP client      │
        │  (TTS)      │      tools+skill     └──────────────────┘
        └─────────────┘
          faster-whisper   edge-tts / CosyVoice (pluggable)
          ▲ fully offline           ▲ swap via env var

Los motores son conectables — configura una variable de entorno para intercambiar cualquiera de los dos lados:

Consulta .env.example para todas las opciones.

Herramientas MCP

La Agent Skill incluida (skills/voice-control) enseña al agente cuándo usarlas: respuestas habladas breves, anuncios de voz antes de tareas largas, espejo de idioma y una degradación elegante a texto.

Solución de problemas

La descarga del modelo falla (errores de red desde huggingface.co): descarga el modelo manualmente desde un espejo y luego haz que WHISPER_MODEL apunte a la carpeta:

bash scripts/download_model.sh tiny            # or base / small
export WHISPER_MODEL="$HOME/.voxagent/models/tiny"

El script descarga de hf-mirror.com con curl simple, evitando por completo el SDK de huggingface_hub. Alternativamente, configura HF_ENDPOINT=https://hf-mirror.com y HF_HUB_DISABLE_XET=1 antes de ejecutarlo si el SDK funciona para ti.

Mantener pulsada la tecla de acceso rápido escribe caracteres en la aplicación enfocada (p. ej., ctrl+j envía saltos de línea en una terminal, desplazándola mientras hablas): en macOS el demonio absorbe la tecla de carácter de la combinación mientras se mantiene. Si el supresor no está disponible, prefiere una combinación sin caracteres como --hotkey f6 o --hotkey ctrl+cmd+j.

Las teclas de acceso rápido de macOS no responden: concede a tu terminal el permiso Accesibilidad / Monitorización de entrada en Ajustes del Sistema → Privacidad y seguridad y, a continuación, reinicia el demonio.

Hoja de ruta

• Tecla de acceso rápido global de pulsar para hablar (voxagent ptt)

• STT en streaming (transcripciones parciales mientras hablas)

• Memoria de voz: clona tu propia voz para las respuestas del agente

• Recetas de integración con OpenClaw / n8n

• Imagen de Docker con CosyVoice integrado

Contribuciones

Se agradecen las issues y los PRs, especialmente nuevos adaptadores de motor (GPT-SoVITS, F5-TTS, Piper...). Cada adaptador tiene ~40 líneas; consulta voxagent/tts/cosyvoice_engine.py para ver el patrón.

Licencia

MIT