agent-talkback

Your coding agent reads its replies aloud, in a voice cloned from your own recordings.

You keep working while it talks. You hear what it is about to do, then what it found, and you can pause it, jump back ten seconds, or shut it up, without leaving the terminal.

npx agent-talkback install

Works with Claude Code and Codex, on macOS and Linux.

What you get

• Your voice, not a robot one. One clean recording of you talking, ten seconds or so, is enough for it to copy. Nothing is sent anywhere: the voice is made on your own machine.
• The useful parts only. By default you hear two things per turn: the opening line, which says what the agent is about to do, and the closing summary, which says what came of it. The working in between stays quiet. talkback full reads everything instead.
• Playback you control. Pause, resume, jump back, replay, loop, stop.
• No code read aloud. Code blocks, tables, file paths and links are dropped on the way through, because they sound like noise.

What it needs

| | | |---|---| | uv | installs and runs the Python side. curl -LsSf https://astral.sh/uv/install.sh \| sh | | ffmpeg | only to cut a voice clip. brew install ffmpeg | | A graphics chip | an Apple M-series or an Nvidia card makes speech at about the speed you hear it. On a plain CPU it is much slower. | | About 5 GB of disk | the libraries, and the voice model it downloads once. |

Installing

npx agent-talkback install                 # Claude Code, every project
npx agent-talkback install --project .     # Claude Code, this project only
npx agent-talkback install --codex         # Codex
npx agent-talkback install --claude --codex --status-line

Everything it puts on the machine goes in two places: ~/.talkback, which holds the voice, your clips and the settings, and your agent's own settings folder, where it registers the hooks and the slash commands. Any file it changes is copied first, so nothing of yours is lost. npx agent-talkback uninstall takes it back out.

Then give it a voice to copy, and switch it on:

talkback add-clip ~/Desktop/recording.mov --start 0:04 --end 0:16
talkback on

Any recording of you talking will do: a voice memo, a screen recording, a meeting you were in. One voice only, no music underneath, no second person, no room echo. That clip decides how good the result sounds, more than any setting does. Seven to twenty-five seconds is the sweet spot.

The first reply after that is slow, because the voice model downloads itself once, about 2 GB. After that a sentence takes about as long to make as it takes to say.

Using it

In Claude Code:

| | | |---|---| | /talkback | flip it on or off | | /talkback full | read every message in full | | /talkback summary | back to the opening line and the summary | | /audio pause, /audio resume | stop and carry on | | /audio seek -10 | jump back ten seconds | | /audio restart | play the reply again | | /audio loop on | keep repeating it | | /audio speed 1.5 | fix the talking speed, or auto to let it adapt | | /audio stop | silence, and skip the rest |

The same from any terminal, as talkback on, talkback audio pause, and so on. talkback speak "some words" says something on demand, switch or no switch. talkback doctor says what is ready and what is missing.

How it works

  agent writes a message
           │
   hook picks it up ──────────► speaker service (stays running)
                                      │
                            Chatterbox makes the sound
                                      │
                                 your speakers

Claude Code fires a hook as each message appears and another when the turn ends, so what you hear is what you are reading. The hook does not do any of the work: it hands the words to a small service that keeps the voice model loaded, because loading it takes about twenty seconds and nobody wants that on every reply. The service shuts itself down after half an hour of quiet. A new message cuts off whatever is still being said, so the voice never trails behind the screen.

Codex has no per-message event, but it does run a program of your choosing when a turn finishes and hands it what was said. So with Codex you hear the closing summary, which is the part most worth hearing.

Speech is made at roughly the speed it is heard, so a long reply would finish late. Two things soften that: the first sentence is cut short so sound starts sooner, and playback speeds up as the backlog grows, up to twice normal, with the pitch unchanged. talkback timing prints the real figures from your own machine, so this can be checked rather than believed.

The last twenty replies are kept as sound files in ~/.talkback/spoken.

Settings

~/.talkback/voice.toml:

[voice]
name = "Narrator"
clips = "voices/narrator"
exaggeration = 0.5   # how much feeling, 0 to 1
pace = 0.5           # lower is faster and flatter

If the clips folder holds several recordings, the largest one is used. To choose, name it reference.wav.

Please clone your own voice

A voice is personal. Use your own, or ask the person first. Cloning somebody's voice without their say-so causes real trouble, legal and otherwise.

Thanks

The speaking is done by Chatterbox from Resemble AI, running entirely on your machine.