🎙️ VoxAgent

Общайтесь со своим агентом разработки. Он отвечает вам.

Локальный голосовой ввод/вывод для Claude Code, Cursor, OpenClaw и любого MCP-клиента.

English · 简体中文

Зачем

Агенты разработки прошли путь от автодополнения до коллег, но интерфейс по-прежнему клавиатура. VoxAgent даёт вашему агенту уши и рот:

• 🎤 listen() — диктуйте инструкции, фрагменты кода или замечания по код-ревью

• 🔊 speak() — голосовые обновления прогресса; идите за кофе, пока ваш агент говорит

• 🗣️ ask_user() — агент спрашивает, вы отвечаете вслух из другого конца комнаты

• 🕹️ Push-to-talk — удерживайте глобальную горячую клавишу в любом месте; ваши слова уходят прямо в claude -p, а ответ озвучивается

Всё работает на вашей машине. STT полностью офлайн (faster-whisper); TTS стартует с голоса без настройки и может быть расширен до локального сервера CosyVoice для речи производственного качества. API-ключи не требуются.

Быстрый старт

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'

Затем просто скажите: "voice mode on" — или удерживайте горячую клавишу PTT (по умолчанию Ctrl+Shift+Space) и говорите.

Работает с любым MCP-клиентом — Cursor, OpenClaw, Codex и другие говорят на MCP.

Архитектура

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

Движки взаимозаменяемы — задайте одну переменную окружения, чтобы заменить любую сторону:

См. .env.example со всеми параметрами.

MCP-инструменты

Встроенный Agent Skill (skills/voice-control) учит агента когда их использовать: короткие голосовые ответы, голосовые объявления перед длительными задачами, зеркалирование языка, плавный откат к тексту.

Устранение неполадок

Не удаётся загрузить модель (сетевые ошибки с huggingface.co): скачайте модель вручную с зеркала, затем укажите WHISPER_MODEL на папку:

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

Скрипт загружает данные с hf-mirror.com обычным curl, полностью обходя SDK huggingface_hub. Если SDK вам подходит, перед запуском можно задать HF_ENDPOINT=https://hf-mirror.com и HF_HUB_DISABLE_XET=1.

Удержание горячей клавиши вводит символы в активное приложение (например, ctrl+j отправляет переводы строк в терминал, прокручивая его, пока вы говорите): в macOS демон поглощает символьную клавишу горячей клавиши, пока удерживается комбинация. Если подавитель недоступен, выбирайте горячую клавишу без символов, например --hotkey f6 или --hotkey ctrl+cmd+j.

Горячие клавиши macOS не реагируют: предоставьте вашему терминалу разрешение Accessibility / Input Monitoring в System Settings → Privacy & Security, затем перезапустите демон.

Дорожная карта

• Глобальная горячая клавиша push-to-talk (voxagent ptt)

• Потоковый STT (частичные транскрипты, пока вы говорите)

• Голосовая память — клонируйте свой голос для ответов агента

• Рецепты интеграции OpenClaw / n8n

• Docker-образ со встроенным CosyVoice

Участие

Принимаются Issues и PR — особенно новые адаптеры движков (GPT-SoVITS, F5-TTS, Piper...). Каждый адаптер — ~40 строк; пример см. в voxagent/tts/cosyvoice_engine.py.

Лицензия

MIT