🎙️ VoxAgent

코딩 에이전트와 대화하세요. 에이전트가 응답합니다.

Claude Code, Cursor, OpenClaw 및 모든 MCP 클라이언트를 위한 로컬 우선 음성 I/O입니다.

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'

그런 다음 **"음성 모드 켜"**라고 말하거나 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"

이 스크립트는 huggingface_hub SDK를 완전히 우회하고 일반 curl로 hf-mirror.com에서 다운로드합니다. 또는 SDK가 동작한다면 실행 전에 HF_ENDPOINT=https://hf-mirror.com과 HF_HUB_DISABLE_XET=1을 설정하세요.

단축키를 누르고 있으면 포커스된 앱에 문자가 입력됩니다 (예: ctrl+j는 터미널에서 줄바꿈을 보내 말하는 동안 화면을 스크롤합니다): macOS에서는 데몬이 콤보가 눌려 있는 동안 단축키의 문자 키를 삼킵니다. 억제기가 없는 경우 --hotkey f6 또는 --hotkey ctrl+cmd+j 같은 문자가 없는 단축키를 사용하는 것이 좋습니다.

macOS 단축키가 반응하지 않음: 시스템 설정 → 개인정보 보호 및 보안에서 터미널에 손쉬운 사용 / 입력 모니터링 권한을 부여한 다음 데몬을 다시 시작하세요.

로드맵

• 푸시투토크 글로벌 단축키 (voxagent ptt)

• 스트리밍 STT (말하는 동안 부분 텍스트 변환)

• 음성 메모리 — 에이전트 응답에 사용할 나만의 목소리 복제

• OpenClaw / n8n 통합 레시피

• CosyVoice가 포함된 Docker 이미지

기여

이슈와 PR을 환영합니다 — 특히 새로운 엔진 어댑터(GPT-SoVITS, F5-TTS, Piper...)가 필요합니다. 각 어댑터는 ~40줄이며, 패턴은 voxagent/tts/cosyvoice_engine.py를 참조하세요.

라이선스

MIT