Free text-to-speech for Claude Code and Codex, from Heard (heard.dev), the voice context layer for agents. Can you use text-to-speech with Claude Code? Yes. This open-source (MIT) repo reads Claude Code updates aloud with your computer's built-in voice: a Stop hook reads each response out loud when a task completes, and a /say skill speaks a short summary when you ask. No API key, no account.
To connect Claude Code hooks to narration, first get the speech script:
git clone https://github.com/heardlabs/claude-code-tts
mkdir -p ~/.claude/skills
cp -r claude-code-tts/plugins/say/skills/say ~/.claude/skills/Then add a Stop hook to ~/.claude/settings.json that pipes Claude's final reply into speak.sh (needs jq):
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "jq -r '.last_assistant_message // empty' | bash ~/.claude/skills/say/speak.sh >/dev/null",
"async": true
}
]
}
]
}
}- Why
last_assistant_message: the Stop hook input carries Claude's final reply in that field. The hooks docs recommend it over readingtranscript_pathfor read-aloud hooks, because the transcript file may not include the final message yet when Stop fires. - Why
"async": true: the hook runs in the background, so Claude never waits for the voice. - What you hear: the raw reply, with markdown stripped and capped at 600 characters by
speak.sh, usingsayon macOS,spd-sayorespeak-ngon Linux, and System.Speech on Windows. Parallel sessions queue instead of talking over each other. - Check it: run
/hooksin Claude Code to see the Stop hook listed, then ask Claude anything short.
Claude Code's /voice command is dictation: it turns your speech into a prompt and does not speak replies back. To hear Claude Code, use the Stop hook above, or type /say for a short spoken briefing (install below).
For short spoken updates from every Claude Code and Codex session on a Mac, with questions and approvals first, use Heard (heard.dev), the voice context layer for agents. It runs on macOS 14 or later, and on Heard Power you can talk back.
Just want a sound when Claude Code finishes or needs you, with no voice? Use claude-code-sound-notification, also from the Heard team: one install command adds a Stop and a Notification hook.
On OpenAI Codex CLI, codex-sound-notification does the same with Codex's notify setting and a PermissionRequest hook.
For a fixed line instead of the whole reply, give speak.sh the text. Use this as the hook command in the same Stop block:
"command": "bash ~/.claude/skills/say/speak.sh 'Claude is done' >/dev/null"For a sound instead of a voice on macOS, use afplay /System/Library/Sounds/Glass.aiff as the command.
A /say skill that speaks a short summary aloud instead of reading every word: what this is, how it went, and who moves next.
> /say
speaking: In the billing service, the refactor is done and all tests pass.
The schema migration is next, and it's your call whether to run it today.
> /say short
speaking: Billing refactor done, migration is your call.
Reading an agent's reply aloud word by word is noise. /say makes the agent write a briefing for the ear first, always in the same three parts:
| Part | What it says | Example |
|---|---|---|
| 1. Context | Which project or task, so you know which session is talking | "In the billing service," |
| 2. Outcome | Done, failed, blocked or still going, plus the one fact that matters | "the refactor is done and all tests pass." |
| 3. Next action + owner | What happens next and who does it. Never ends without an owner | "The migration is your call." / "I'll start the docs next." |
When you have to act, you get what you need to act without opening the terminal:
- A decision: the options, the one trade-off between them, and the agent's recommendation. "Two fixes: raise the timeout, two minutes but the page stays slow, or add an index, an hour but under two seconds. I'd add the index. Your call."
- Something it needs: exactly what, and where it goes. "I need a Stripe test key in the env file to run the payment tests."
- An approval: what will happen and the risk. "I want to drop the old sessions table. It's backed up. Okay to go ahead?"
- Too many options to say: the recommendation out loud, the full comparison on screen.
No code, file paths, URLs or markdown are read aloud. Numbers come out as words ("two tests failed", not "2/14").
Pick the length:
| Command | Length | What you get |
|---|---|---|
/say short |
up to 15 words (20 for a decision) | Context and next action, or the options in a word or two and the pick |
/say |
up to 35 words (50 when you must decide) | All three parts |
/say long |
up to 80 words | All three parts, plus the one risk you should know about, and full options for a decision |
/say <text> |
your text | Reads your text as is |
Codex uses $say the same way. You can also tell the agent "say it out loud when the tests finish".
- A templated briefing, not a transcript. Context, outcome, next action and owner, every time.
- Built for decisions. When it needs you, it says the options, the trade-off and its recommendation.
- Three lengths.
short, normal andlong, so a glance and a full update both work. - Parallel sessions take turns. Several agents speaking at once queue up instead of talking over each other, and the context line tells you which one is talking.
- Never blocks the agent. Speech plays in the background, and the command returns at once.
- On screen too. The same briefing appears in the reply, so you can read it later.
- Nothing to sign up for. It uses the voice your computer already has. No account, no API key, no network.
Claude Code and Codex, as a personal skill (gives you /say and $say):
git clone https://github.com/heardlabs/claude-code-tts
mkdir -p ~/.claude/skills ~/.agents/skills
cp -r claude-code-tts/plugins/say/skills/say ~/.claude/skills/
cp -r claude-code-tts/plugins/say/skills/say ~/.agents/skills/Claude Code, as a plugin (the command is then /say:say):
claude plugin marketplace add heardlabs/claude-code-tts
claude plugin install say@heard-sayThen try /say hello. The first time, Claude Code asks before it runs the speech script: pick "Yes, and don't ask again".
| System | Voice engine | Setup |
|---|---|---|
| macOS | say |
Built in |
| Linux | spd-say, espeak-ng or espeak |
sudo apt install espeak-ng |
| Windows / WSL | PowerShell System.Speech |
Built in |
Set these in your shell profile:
| Variable | What it does | Example |
|---|---|---|
SAY_VOICE |
Voice name (say -v '?' lists them on macOS) |
Samantha, en-us |
SAY_RATE |
Words per minute | 200 |
The script is speak.sh and works on its own too: bash speak.sh "deploy done".
How do I make Claude Code talk out loud?
Install the skill above and type /say. Claude writes a short spoken briefing (context, outcome, next action and owner) and your computer reads it aloud.
How is this different from piping Claude's reply into a TTS command?
A raw reply read aloud is long and full of code and paths. /say has the agent write a few words for the ear in a fixed format first, so you can tell at once which session it is, how it went, and whether it needs you.
Does it work with Codex?
Yes. Copy the skill into ~/.agents/skills and type $say in Codex.
Does it send my code anywhere? No. The text goes straight to your computer's built-in voice. Nothing leaves the machine.
Can it speak automatically every time the agent finishes?
Yes, with a Claude Code Stop hook. See the Stop hook section at the top for the exact settings.
Can I listen to Claude Code output instead of reading dense terminal text?
Yes. /say gives you a short spoken briefing on demand, and the Stop hook above reads each final reply aloud as it lands.
A raw reply read aloud is often long and full of code. That is the gap /say fills for one session, and the gap Heard fills for many: this skill comes from the team behind Heard (heard.dev), the voice context layer for agents on macOS. Heard follows your Claude Code and Codex sessions and tells you in a sentence or two when an agent finishes, fails or needs your approval, and you can talk back. The Mac app is a managed build. There is also a separate open-source engine (Apache 2.0) you can build yourself, which runs fully local with Kokoro text-to-speech.
bash tests/speak.test.sh: 18 checks on the speech script with fake voice engines (engines and options, stdin, markdown stripping, length cap, background playback, queueing without overlap, stale locks). Runs in CI.node tests/eval/run.mjs: briefing quality. 17 scenarios (done, failed, blocked on a secret, two, three and six-option decisions, destructive approval, path-heavy and number-heavy updates, all three lengths, literal text). Each runs a real headless Claude Code session with the skill, captures what it says, checks word limits and that no paths, URLs or code are read aloud, then a judge model grades context, outcome, owner, whether you could act on it, and faithfulness. Needs theclaudeCLI.