Telling Technology · Learning in public
All episodes
EP.83
A Claude Code workflow, out loud

My AI started talking back

I had already stopped typing — dictation in, hands free. But every answer still ended the same way: look at the screen and read. So I gave the terminal a mouth. Every reply is now spoken out loud by a voice engine that runs entirely on this machine — no account, no API key, no audio leaving the box.

A dark terminal window with a Claude Code reply on screen and a soft teal audio waveform rising out of it toward a pair of speaker arcs, suggesting the text is being spoken aloud
⎍ fully local TTS · 0 API calls · 0 kr/month
The loop was only half hands-free, and I had not noticed which half.
01 The half-loop

Hands-free in. Eyes-on out.

I drive Claude Code over remote desktop and dictate into it — press the dictation key, talk, send. That half of the loop has been solved for months and it genuinely changed how I work: I can pace, I can hold a coffee, I can think out loud instead of composing sentences with my fingers. But the reply always landed as text. So every single exchange ended with me turning back to the screen and reading. Which means the workflow was never actually hands-free — it was hands-free on the way in and screen-bound on the way out. The bottleneck had quietly moved, and because the input side felt so good I had stopped noticing the output side at all.

claude code — desktop
> I dictate everything to you now and I still have to stare at the screen to find out what you said. Can you just read your answers to me?
Yes — and you already own the hard part. You have a local text-to-speech engine running for the phone voice AI. The missing piece is not a voice, it is a trigger: a Stop hook that fires when I finish a reply, pulls the last assistant message out of the transcript, and hands it to that engine. No new service, no new key.
A loop diagram where the inbound arrow is labelled voice and glows, and the outbound arrow is labelled screen and is greyed out, showing only half the loop is hands-free
half a loop
Voice in, text out. The eyes were still doing the last mile.
02 Reuse, not rebuild

The voice was already in the building

Back in June I built a phone voice-AI web app, and it speaks through Piper — a small offline text-to-speech binary with a downloaded voice model. That binary was already on disk, already working, already paid for by being free. So the build here was not “add TTS”, it was “point a second consumer at the engine I already have.” A script, speak-reply.py, reads the last assistant message straight off the session transcript, strips it into something a human would actually want spoken — code fences out, URLs out, markdown symbols out — caps it at roughly 45 seconds so a long answer gives me the lead rather than a monologue, and pipes it to Piper. One engine, two surfaces: the phone had a voice; now the terminal has the same one.

claude code — desktop
> Don’t read me the code blocks. And don’t read me a five-minute essay either.
Handled in the sanitizer: fenced blocks and inline code are dropped, bare URLs collapse to “link”, and markdown punctuation is stripped so you don’t hear asterisks read aloud. Then the speakable text is truncated to roughly 45 seconds. You get the headline out loud; the detail stays on screen for when you want it.
A diagram with one Piper voice-engine block in the centre feeding two surfaces: a phone showing a voice-AI app on the left and a desktop terminal on the right
one engine, two mouths
The phone app and the terminal hook speak with the exact same binary and voice model.
03 The guardrails

A talking agent needs an off switch before it needs a voice

The moment anything speaks automatically, the interesting engineering is in when it must not. Two layers. First, a plain flag file — tts-on.flag — that toggles the whole thing on and off, and which I can flip by just saying “tts off” in chat. Second, and more important, an environment guard: AIOS_TTS_OFF=1 hard-mutes the hook for the Telegram listener and for unattended claude -p runs. Without it, a headless agent at 3am would cheerfully narrate itself to an empty room and pay the synthesis latency on every single turn. The env guard is not a nicety — it is what keeps a UI feature out of the automation path.

claude code — desktop
> The nightly builds run unattended. Make sure they never try to talk.
Set AIOS_TTS_OFF=1 in the environment those runs inherit and the hook exits before it touches Piper — no synthesis, no wait, no audio device. The flag file stays for the interactive on/off; the env var is the hard mute that automation cannot accidentally undo.
Two stacked guard layers drawn as switches: a soft toggle labelled tts-on.flag and below it a hard cut-off labelled AIOS_TTS_OFF=1 blocking a headless agent icon
soft toggle, hard mute
The flag is for me. The env var is for every run where nobody is listening.
⚠️

Honest about what this is not

This is a local, small, offline voice model — it is clear and it is fast, but it is not a studio narrator, and it will mispronounce your project names. There is also a real cost per reply: synthesis takes a beat before audio starts, which is exactly why the unattended path is hard-muted rather than merely discouraged. And the ~45s cap means long answers are deliberately truncated — you hear the lead, not the whole thing. That is a choice, not a limit of the engine.

04 The build, in four frames

What actually shipped

The hook, the sanitizer, the toggle and the two-surface picture — the whole feature is four small pieces. Tap any image to enlarge it and read the exact prompt that drew it.

RECORDED LIVE · AUDIO ON

Ask it a question. Look away. Hear the answer.

The demo is deliberately boring to describe and strange to experience: I dictate a question, turn away from the monitor entirely, and the machine answers me out loud a few seconds later. No browser tab open, no request leaving the network, no key in an env file anywhere. The whole exchange — my voice in, its voice out — happens on one computer.

A desk seen from behind: a terminal on screen with a reply, the person turned away from it, and a waveform in the air between the speakers and their ear
dictated question → Stop hook → sanitizer → Piper → audio · entirely offline
06 Steal this

Give your own terminal a voice

The Stop hook, the sanitizer and the toggle are small enough to read in one sitting. Everything in this episode is free and open — clone it, run it, make it yours.

skill speak-reply.py (transcript reader + sanitizer + 45s cap) cmd Stop hook entry for settings.json template tts-on.flag toggle + AIOS_TTS_OFF env guard assets Piper voice-model notes (small offline English voice)
run it repo not published yet — the hook lives inside the private AIOS workspace; the script, the sanitizer rules and the env guard are walked through line by line in the video

No GitHub? Comment SPEAK on the post and the bot DMs you the link.

Next episode

Then git push stopped working — for the whole repo

A secrets-scanning baseline I had never audited quietly grew a backlog, and one morning it blocked every push in the repository. Not one file. All of them. The fix shipped as an explainer page before lunch.

A darkened teaser of a blocked git push in a terminal with a red pre-commit hook message
drops soon · follow so you don’t miss it