agents-voice

Fast, minimal multi-provider speech output MCP server and CLI for AI coding agents.
Zero heavy dependencies. Pure Python standard library audio playback with seamless Dumbo HUD bridge synergy.

Overview

agents-voice equips AI coding agents (Antigravity, Cursor, Zed, Claude, agents-harness) with a native voice tool (voice_speak). Instead of reading long code diffs or screen-scraping text, the agent formulates a concise, natural spoken summary (1–2 sentences) directly to the developer's ears upon completing tasks.

Highlights

• Multi-Provider Support: Out-of-the-box support for Azure Speech (48kHz DragonHD), OpenRouter (gpt-audio PCM16 streaming, gpt-4o-mini-tts), OpenAI, Google Gemini 2.5 TTS, ElevenLabs, and custom OpenAI-compatible local endpoints (e.g., Kokoro, LocalAI).
• Zero Heavy Dependencies: Pure Python standard library (urllib.request, winsound / winmm on Windows, native OS audio players on macOS/Linux). No ffmpeg, no pygame, no C compiler required.
• Standalone or HUD Synergy: Plays directly through OS audio when standalone. If the Dumbo desktop overlay is running (127.0.0.1:12480), optionally routes through Dumbo's Veadio HUD for synchronized word-by-word highlighted playback.
• Local Credentials: Kept securely on the local machine in ~/.agents/voice.json with fallback discovery from environment variables and existing Dumbo settings.

Installation

pip install agents-voice

Or install in editable mode from source:

git clone https://github.com/Lolaplex/agents-voice.git
cd agents-voice
pip install -e .

Configuration

Credentials and settings are saved to ~/.agents/voice.json:

Azure Speech (Default)

agents-voice config --provider azure --key "YOUR_AZURE_KEY" --region "swedencentral" --voice "de-DE-Seraphina:DragonHDLatestNeural"

OpenRouter (Steerable & GPT Audio Streaming)

agents-voice config --provider openrouter --key "YOUR_OPENROUTER_KEY" --model "openai/gpt-4o-mini-tts" --voice "marin"

OpenAI

agents-voice config --provider openai --key "YOUR_OPENAI_KEY" --model "gpt-4o-mini-tts" --voice "marin"

Google Gemini

agents-voice config --provider gemini --key "YOUR_GEMINI_KEY" --model "gemini-2.5-flash-preview-tts" --voice "Kore"

ElevenLabs

agents-voice config --provider elevenlabs --key "YOUR_ELEVENLABS_KEY" --voice "JBFqnCBsd6RMkjVDRZzb"

Custom / Local Endpoint (e.g. Kokoro, LocalAI)

agents-voice config --provider custom --base-url "http://127.0.0.1:8880/v1" --voice "af_heart"

MCP Server Setup

Add to your MCP configuration (e.g. ~/.cursor/mcp.json, ~/.agents/mcp.json, or Claude Desktop config):

{
  "mcpServers": {
    "agents-voice": {
      "command": "python",
      "args": ["-m", "agents_voice", "serve"]
    }
  }
}

MCP Tools

CLI Reference

License

MIT License. See LICENSE for details.