🎙️ VoxAgent

Sprich mit deinem Coding-Agenten. Er antwortet.

Lokale Sprach-Ein-/Ausgabe für Claude Code, Cursor, OpenClaw und jeden MCP-Client.

English · 简体中文

Warum

Coding-Agenten haben sich von Autovervollständigung zu Kollegen entwickelt – aber die Schnittstelle ist immer noch eine Tastatur. VoxAgent gibt deinem Agenten Ohren und einen Mund:

• 🎤 listen() — Diktiere Anweisungen, Code-Snippets oder Code-Review-Feedback.

• 🔊 speak() — Gesprochene Fortschrittsmeldungen; hol dir einen Kaffee, während dein Agent spricht.

• 🗣️ ask_user() — Der Agent fragt, du antwortest laut aus dem Nebenzimmer.

• 🕹️ Push-to-talk — Halte einen globalen Hotkey an beliebiger Stelle gedrückt; deine Worte gehen direkt in claude -p, und die Antwort wird zurückgesprochen.

Alles läuft auf deiner Maschine. STT ist vollständig offline (faster-whisper); TTS startet mit einer Stimme ohne Einrichtung und kann auf einen lokalen CosyVoice-Server aufgerüstet werden, für Sprachausgabe in Produktionsqualität. Keine API-Schlüssel erforderlich.

Schnellstart

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'

Sag dann einfach „voice mode on“ – oder halte den PTT-Hotkey (Standard Ctrl+Shift+Space) gedrückt und sprich.

Funktioniert mit jedem MCP-Client – Cursor, OpenClaw, Codex und Co. sprechen alle MCP.

Architektur

        ┌─────────────┐     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

Engines sind austauschbar – eine Umgebungsvariable genügt, um eine der beiden Seiten zu wechseln:

Alle Optionen findest du in .env.example.

MCP-Tools

Die gebündelte Agent Skill (skills/voice-control) bringt dem Agenten bei, wann sie verwendet wird: kurze gesprochene Antworten, Sprachankündigungen vor langen Aufgaben, Spiegelung der Nutzersprache, eleganter Rückgriff auf Text.

Fehlerbehebung

Fehler beim Herunterladen des Modells (Netzwerkfehler von huggingface.co): Lade das Modell manuell von einem Mirror herunter und setze WHISPER_MODEL auf den Ordner.

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

Das Skript lädt von hf-mirror.com mit einfachem curl herunter und umgeht das huggingface_hub SDK vollständig. Alternativ kannst du vor dem Ausführen HF_ENDPOINT=https://hf-mirror.com und HF_HUB_DISABLE_XET=1 setzen, falls das SDK bei dir funktioniert.

Hotkey gedrückt halten gibt Zeichen in die fokussierte App ein (z. B. sendet ctrl+j in einem Terminal Zeilenumbrüche und scrollt es, während du sprichst): Unter macOS verschluckt der Daemon die Zeichentaste des Hotkeys, solange die Kombination gehalten wird. Falls der Unterdrücker nicht verfügbar ist, verwende besser einen zeichenfreien Hotkey wie --hotkey f6 oder --hotkey ctrl+cmd+j.

macOS-Hotkeys reagieren nicht: Erteile deinem Terminal die Berechtigung Bedienungshilfen / Eingabeüberwachung in den Systemeinstellungen → Datenschutz & Sicherheit und starte den Daemon anschließend neu.

Roadmap

• Globaler Push-to-talk-Hotkey (voxagent ptt)

• Streaming-STT (partielle Transkripte während du sprichst)

• Sprachgedächtnis – klone deine eigene Stimme für Antworten des Agenten

• Integrationsrezepte für OpenClaw / n8n

• Docker-Image mit gebündeltem CosyVoice

Mitwirken

Issues und PRs sind willkommen – insbesondere neue Engine-Adapter (GPT-SoVITS, F5-TTS, Piper...). Jeder Adapter umfasst ~40 Zeilen; das Muster findest du in voxagent/tts/cosyvoice_engine.py.

Lizenz

MIT