claude-read-aloud

Hear Claude's replies instead of reading them. A speaker button inside
Claude Code's chat box, right-click Read aloud on any highlighted text, a
hotkey, and a settings panel in Claude's own sidebar — voices from free system
TTS up to Speechify / ElevenLabs / OpenAI with your own key.

If you work with Claude Code all day, you read all day — and at some point you
stop absorbing and start skimming. Listening shifts the load from your eyes to
your ears: you take in the whole answer, keep your eyes on the code it
describes, and reply better. And when reading itself is the hard part — low
vision, dyslexia, screen fatigue — it makes Claude Code usable at all.

Free out of the box: system voices with zero setup, or one command installs
Kokoro, a genuinely good local neural voice — no account, no key, 54 voices.

▶ Watch the 30-second demo

Two pieces

Install the plugin first (it's the engine), then the extension if you use
VS Code. Terminal-only users need just the plugin.

Install

claude plugin marketplace add michaelpgifford/claude-read-aloud
claude plugin install read-aloud@claude-read-aloud

(Same two steps work inside Claude Code as /plugin marketplace add … and
/plugin install …, or from a local clone by passing its path to
marketplace add.)

Requires Python 3.9+ on your PATH (python3, or python on Windows).
No packages to install — the whole engine is one standard-library script.

Use

On Linux, run /read-aloud:voice-setup first. macOS and Windows system
voices are decent out of the box; Linux's stock voice is espeak, which is not.
One command and ~340MB later you have a genuinely pleasant local voice, free
forever — the plugin will remind you once if you skip this.

(Type /speak and let completion fill the namespace — commands are listed
under their plugin name.)

Long replies start speaking in ~1–3 seconds regardless of length: text is
split at sentence boundaries into ramped chunks (small first — its size is
the time-to-first-sound), and each next chunk synthesises while the previous
one plays, so there are no gaps.

Voices

Config lives at ~/.config/claude-read-aloud/config.json
(%APPDATA%\claude-read-aloud\config.json on Windows):

{
  "provider": "speechify",
  "voice": "oliver",
  "speed": 1.0,
  "auto_read": false
}

voice is the provider's own voice name/id (macOS: say -v '?' lists yours;
cloud providers list voices in their consoles). API keys go in environment
variables, never in the file.

A local neural engine plugs in through command — {text} is replaced with
the text to speak; add {out} if your engine writes a WAV for the plugin to
play (that's what enables gapless chunking):

{
  "provider": "command",
  "command": "piper -m /path/to/voice.onnx -f {out}"
}

The fine print that saves you a support ticket

• Auto-read is off by default, on purpose. A working session produces hours
  of speech per day (we measured 4+). Try /speak-auto on — most people come
  back to on-demand within a day, and that's the intended workflow.
• Replies cap at 12,000 characters (~14 minutes) and say so when cut.
  Code blocks are spoken as "code omitted" — nobody wants JSON read aloud.
• Stop always works mid-sentence: /speak-stop, or the button/hotkey below.
• Speechify's WAV arrives with broken (streaming) header sizes; the plugin
  repairs them — if you ever hear a burst of static with another tool, that's
  what it was.

Buttons and hotkeys in VS Code

The companion extension adds, safely and update-proof:

• a status-bar Read aloud button (bottom-left, under the chat input),
• a toolbar icon on the Claude Code panel,
• Ctrl+Alt+S / Ctrl+Alt+X (⌘⌥S / ⌘⌥X on macOS),
• the settings panel, voice picker, right-click menu, and in-chat button below.

Install it from the VS Code Marketplace — search "Claude Read Aloud", or:

code --install-extension MichaelGifford.claude-read-aloud-button

It auto-detects the installed plugin. (From source instead: clone this repo,
npx @vscode/vsce package in vscode-extension/, and install the .vsix
via Extensions → … → Install from VSIX.)

The status-bar button sits bottom-left, directly under the chat input, and the
toolbar icon rides on the Claude Code panel itself:

The good stuff: in-chat button + right-click "Read aloud"

The two triggers that actually feel native — and, in daily use, the ones you
end up reaching for:

• A speaker button inside the chat box, right next to the mic. Click it and
  it reads the reply you're looking at (it reads the visible conversation, so
  it can't pick the wrong session). Highlight text first and it reads just that.
• Highlight any text in the chat → right-click → "Read aloud" in the same
  menu as copy/paste.

The speaker sits right where your eyes already are, next to the mic:

Highlight, right-click, and it's in the same menu as copy and paste:

The extension offers this once on startup (a small toast); or run
"Claude Read Aloud: Install in-chat button" from the Command Palette,
confirm, reload. Undo any time with "Remove in-chat button".

Settings panel and voice picker

A Read Aloud section lives inside Claude Code's own sidebar: current voice
with test, provider switcher, speed, auto-read, and the in-chat button toggle.
Change voice… opens a searchable picker of the current provider's voices —
selecting one saves it and plays a sample in that voice immediately.

Read this part before enabling it. VS Code offers no way to put a button
inside another extension's webview, so this works by patching two files of
the installed Claude Code extension on your machine:

• webview/index.js gets a script appended (never spliced — an upstream
  change can stop it matching, but can't corrupt the bundle) that inserts the
  button and captures right-click selections.
• extension.js's Content-Security-Policy gains one directive,
  connect-src http://127.0.0.1:48777, so the button can reach this
  extension's local server. That is a real, if small, widening of the webview
  sandbox — one localhost port — and it's the entire reason this is opt-in
  rather than default.

Originals are backed up beside each file (*.cra-orig) and restored exactly on
removal. Every Claude Code update wipes the patch; the extension notices on
startup and re-applies it, asking you to reload. Worst case, the button
disappears until the next reload — the hotkeys and status-bar button never
depend on it. If you previously hand-patched these files with something else,
revert that first; the patcher refuses to stack two injections.

This is a userscript-style local mod, in the same spirit as browser extensions
that add buttons to websites. It never leaves your machine. The right fix is
Anthropic shipping a TTS affordance natively — if you want that, add your
voice to a feature request on
anthropics/claude-code.

How it decides what to read

• /speak and auto-read use the session's own transcript (hooks receive the
  exact path — never a guess).
• The VS Code button scopes to the window's workspace, so a busier session in
  another project can't hijack what gets read.

License

MIT.