agent-voice
Open source under the MIT licence. View the source
A small Python tool that turns an agent's reply into one spoken in-character line in a voice cloned from a 3 to 10 second clip.
The problem
The screen keeps the full technical reply while the speaker gets one short line, so an agent can talk without a browser in the loop. It grew out of a Claude Code session that wanted to talk as Skippy.
How it works
Three entry points (agent-voice speak, agent-voice pipe, and agent-voice serve with POST /say) pick the spoken line in --mode auto: an explicit <say> tag if the agent wrote one, otherwise a small OpenAI-compatible writer model that reads the reply plus the voice's persona.md, otherwise the text directly. The line is sent to an OmniVoice TTS server (/health + /synthesize contract) and played. Voices are directories holding ref.wav, ref.txt, optional language.txt and persona.md. Utterances are serialized so two agents take turns.
Features
- CLI, stdin pipe and HTTP server (POST /say) doors, plus a Python Speaker API
- Tag, writer-model or direct line selection with --mode override
- Works with any OmniVoice server using the /health + /synthesize contract
- agent-voice doctor names every missing piece and its fix
- Claude Code integration with two hooks and a toggle
- About 600 lines, one dependency (httpx), 20 tests, mypy strict (per README)
How it was built
The first commit on 2026-08-27 shipped version 0.1.0: a tool that lets a Claude Code session speak a short line in a character voice while the screen keeps the full reply.
The design kept two channels apart because a whole technical reply read aloud is slow and mostly unspeakable. The spoken line comes from an explicit say tag first, a writer model second, and stripped text last.
It reused the synthesis API that existing OmniVoice servers already expose instead of inventing one, and kept a single runtime dependency so it could sit next to any agent.
Sixteen minutes after the first commit, a release pass added an installer, an install guide and a doctor command that prints the fix for each failure. Review in that pass caught the formatter rewriting code inside Markdown and a doctor check that failed when playback was off.
The tool was built with AI coding agents in the same setting it serves, and Rico decided the scope. It is feature-complete at 0.1.0, with 22 tests running on Ubuntu and macOS.