Ava
Voice conversations for AI coding assistants over MCP.
Ava runs a local MCP HTTP server, speaks through ElevenLabs TTS, listens through ElevenLabs Scribe realtime STT, and coordinates the microphone with a conch lock so multiple agents do not talk over each other.
What It Does
- Voice conversation tool for Claude Code, Cursor, and other MCP clients
- ElevenLabs
eleven_v3 TTS with configurable voice, model, speed, and instructions
- ElevenLabs Scribe realtime STT with local Silero VAD and manual commit mode
- Optional audio ducking, chimes, conversation logging, and saved audio artifacts
- Optional Claude Code hooks for soundfont feedback and Ava Connect notifications
- Local launchd helper for running the HTTP server on
127.0.0.1:8765
Quick Start
Install dependencies and start the local server:
uv sync
./scripts/ava-server.sh setup
./scripts/ava-server.sh status
Add the MCP server to a client:
{
"mcpServers": {
"ava": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
Required user config lives in ~/.ava/ava.env:
ELEVENLABS_API_KEY=sk_...
AVA_ELEVENLABS_TTS_MODEL=eleven_v3
AVA_ELEVENLABS_STT_MODEL=scribe_v2_realtime
AVA_TTS_SPEED=1.2
Project overrides can go in a repo-local .ava.env.
CLI
uv run ava --version
uv run ava serve --host 127.0.0.1 --port 8765
uv run ava converse
uv run ava claude hooks list -s all
uv run ava soundfonts status
The installed command is ava. The Python package is ava.
Server Management
The repo includes a launchd wrapper for local development:
./scripts/ava-server.sh setup
./scripts/ava-server.sh start
./scripts/ava-server.sh stop
./scripts/ava-server.sh restart
./scripts/ava-server.sh status
./scripts/ava-server.sh logs
./scripts/ava-server.sh health
Logs are written under ~/.ava/logs/. The main structured log is ~/.ava/logs/ava.log; launchd stderr is ~/.ava/logs/server.err.
After code changes, restart the server when you are ready for the running process to pick them up. Do not restart during active playback or a live voice turn.
Claude Code Hooks
Hooks are opt-in. They are not installed by default.
uv run ava claude hooks add
uv run ava claude hooks list -s all
uv run ava claude hooks remove
Installed hooks can play soundfont feedback for tool events and support Ava Connect session/notification behavior. Soundfont playback defaults to enabled only after hooks are installed; disable it with:
uv run ava soundfonts off
uv run ava soundfonts off --config
Development
Use uv for Python work:
uv run pytest -q
uv build
cd installer && uv build
Useful focused checks:
uv run python -c "from ava.server import mcp; from ava import __version__; print(__version__)"
uv run ava --version
Repository Layout
ava/ - Python package and MCP server implementationava/tools/ - MCP tool implementationsava/data/hooks/ - Claude Code hook definitions and shell receiversava/templates/ - launchd/systemd/script templatesinstaller/ava_install/ - installer packagescripts/ava-server.sh - local launchd server helperdocs/ - user and developer documentationtests/ - pytest suite
Documentation
Upstream Acknowledgement
This project is thanks to the great work done by the original upstream repo, mbailey/ava, created by Mike Bailey and the Failmode project. This fork keeps that foundation and adapts the codebase around the renamed Ava package, ElevenLabs-first runtime, local MCP server workflow, and repo-specific development setup.
License
MIT. See LICENSE.
mcp-name: com.failmode/ava
