voiceloop

voiceloop reads Claude Code's replies aloud on your Windows PC, even when Claude Code runs on a different machine.

A small hook in Claude Code sends each finished reply to voiceloop.exe on your desk PC. voiceloop turns the text into speech with Kokoro, plays it, and shows a small pill on screen while it talks. Questions and permission prompts get their own chimes, so you can look away while an agent works and still know when it needs you.

What it does

• Speaks each reply once Claude finishes, and starts talking about 1.3 s after the reply arrives, even for long replies.
• Plays three rising notes before reading out a question (AskUserQuestion), and a ding-dong-ding for permission prompts.
• Skips code blocks, tables and URLs, and reads /resend as "slash resend" and ~/code/project as "project".
• Handles many threads. By default only the thread you last typed into speaks. You can mute a thread with /mute, or have every unmuted thread speak in turn.
• Reads the last reply again when you type /resend (or /repeat).
• Stays quiet while the PC is locked.
• Ctrl+Alt+V turns voice mode on or off, and Ctrl+Alt+X stops speech.
• Sets up the macropad (see The macropad) from its Settings panel, with no vendor software. It can also export key symbols as an STL file for 3D printing.

How it fits together

The diagram at the top shows the whole loop:

1. You type a prompt, or dictate it with Handy, in T3 Code or Claude Code on your Windows PC.
2. The prompt goes to Claude Code on your server, through the T3 server if you use T3 Code.
3. When Claude finishes a reply, asks a question or needs your approval, Claude Code runs voiceloop_hook.py through its hooks (Stop, PreToolUse for AskUserQuestion, and Notification).
4. The hook strips code and markdown and sends the plain text to voiceloop.exe on your PC: a POST /speak on port 8765 with your token.
5. voiceloop.exe sends the text to Kokoro (POST /v1/audio/speech) one sentence chunk at a time and gets WAV audio back.
6. It plays the audio through your speakers and shows the pill while it talks.

The server never plays anything: Claude Code only sends text, and the speech is made and played at your desk.

All three can be the same Windows PC. voiceloop was built for the split case: Claude Code on a headless server, you at a desk, and speech made on whatever box has spare CPU.

Part	Runs on	Needs
voiceloop.exe	Windows 10 or 11, 64-bit (tested on 11)	Nothing else. It's a single 9 MB exe
hooks/voiceloop_hook.py	Anywhere Claude Code runs	Python 3.8 or later, standard library only
Kokoro, or another speech server	Any machine with Docker	About 2 GB of memory for Kokoro. A CPU is enough

Install

1. Start Kokoro

Follow docs/kokoro.md. In short, run docker compose up -d in the kokoro/ folder and check that http://that-box:8880/health answers.

Already run another speech server with an OpenAI-style /v1/audio/speech endpoint, such as Speaches? That works too. See Other speech servers.

2. Install voiceloop on the Windows PC

1. Download voiceloop-<version>-windows.zip from Releases and unzip it.

2. Right-click install.ps1, choose Run with PowerShell, and allow it. To let only your Claude Code machine through the firewall, run it from an administrator PowerShell instead: powershell -ExecutionPolicy Bypass -File install.ps1 -HookFrom 192.168.1.20.

3. Settings opens. Under Voice, enter Kokoro's address (http://127.0.0.1:8880 if it runs on this PC), press Test connection, and pick a voice.

The exe isn't code-signed, so Windows SmartScreen may say it "protected your PC". Choose More info, then Run anyway. Each release lists the exe's SHA256 so you can check the download first.

voiceloop lives in %LOCALAPPDATA%\VoiceLoop, starts when you log on, and has a Start menu entry. To remove it, run install.ps1 -Uninstall.

3. Pair the hook

On the machine that runs Claude Code:

1. Clone this repo, or copy hooks/voiceloop_hook.py somewhere it can stay.

2. In voiceloop, open Settings, About, pick the address your Claude Code machine can reach, and press Copy command.

3. Paste and run that command next to voiceloop_hook.py. It looks like this:

   python3 voiceloop_hook.py setup --url http://192.168.1.50:8765 --token 3f9c...
   

   It saves the address and token to ~/.config/voiceloop/hook.json (%APPDATA%\VoiceLoop on Windows), adds four hooks to ~/.claude/settings.json after a dated backup, and sends a test phrase. You should hear it.

4. Start a new Claude Code session. Replies are now read out.

python3 voiceloop_hook.py test sends the test phrase again. python3 voiceloop_hook.py remove takes the hooks back out of settings.json.

Using it

• Threads. If you use T3 Code, the pill shows the T3 thread's name. With plain Claude Code it shows the project folder. Settings, Threads lists the threads voiceloop has heard and lets you mute each one.
• Commands. Type these in Claude Code. voiceloop handles them, and Claude never sees them.
  • /mute and /unmute mute or unmute the current thread.
  • /resend, /repeat and /replay read the last reply again.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗