# Claude Read Aloud

> A Claude Code plugin and VS Code extension that reads Claude's replies aloud using free local voices or premium TTS APIs like ElevenLabs, OpenAI, and Speechify.

Claude Read Aloud is an open-source MIT-licensed project by Michael Gifford that adds text-to-speech playback to Claude Code, letting developers listen to AI replies instead of reading them. It ships as two pieces: a Claude Code plugin (the audio engine) and an optional VS Code extension (the UI layer with buttons, hotkeys, and a settings panel). The project is available on GitHub and free to use out of the box with system voices.

## What It Is

Claude Read Aloud is a developer accessibility and productivity tool that converts Claude Code's chat replies into spoken audio. It targets developers who spend long sessions in Claude Code and want to reduce eye strain, improve information absorption, or make the tool usable for those with low vision, dyslexia, or screen fatigue. The plugin handles chunked audio synthesis and playback; the VS Code extension surfaces controls natively inside the editor.

## How the Two-Piece Architecture Works

The project is split deliberately into an engine and a UI layer:

- **Claude Code plugin** — handles all voice synthesis, chunked playback, `/read-aloud:*` slash commands, and an auto-read hook. Written in Python using only the standard library (no pip installs required). Requires Python 3.9+.
- **VS Code extension** — adds a status-bar Read Aloud button, a toolbar icon on the Claude Code panel, keyboard shortcuts (Ctrl+Alt+S / Ctrl+Alt+X), a right-click "Read aloud" context menu, an in-chat speaker button beside the microphone, and a settings panel with a searchable voice picker inside Claude's sidebar.

Terminal-only users need only the plugin. VS Code users install both.

## Voice Provider Options

The plugin supports a range of TTS providers, from fully free to premium cloud APIs:

- **System** (default) — macOS `say`, Linux speech-dispatcher, or Windows SAPI; zero setup
- **Kokoro** — free local neural voice with 54 voices, installed via `/read-aloud:voice-setup` (~340 MB one-time download, no account needed)
- **Speechify** — cloud API, requires `SPEECHIFY_API_KEY` environment variable
- **ElevenLabs** — cloud API, requires `ELEVENLABS_API_KEY`
- **OpenAI** — cloud API, requires `OPENAI_API_KEY`
- **Command** — custom template for any local engine (e.g., Piper), enabling gapless chunked playback via WAV output

API keys are stored in environment variables, never in the config file. Configuration lives at `~/.config/claude-read-aloud/config.json` (or `%APPDATA%\claude-read-aloud\config.json` on Windows).

## Playback Design and Accessibility Tradeoffs

Long replies begin playing within 1–3 seconds regardless of length. Text is split at sentence boundaries into ramped chunks — the first chunk is small so audio starts immediately, while subsequent chunks synthesize in parallel with playback, eliminating gaps. Replies are capped at 12,000 characters (~14 minutes of speech), and code blocks are announced as "code omitted" rather than read verbatim. Auto-read is off by default; the README notes that a full working session can produce 4+ hours of speech per day, and most users prefer on-demand triggering.

The in-chat speaker button works by patching two files of the installed Claude Code extension locally — a userscript-style mod that is opt-in, never leaves the machine, and is automatically re-applied after Claude Code updates. Originals are backed up and fully restorable.

## Setup Path

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

The VS Code extension is available on the VS Code Marketplace as "Claude Read Aloud" or via `code --install-extension MichaelGifford.claude-read-aloud-button`. Linux users are prompted to run `/read-aloud:voice-setup` once to replace the default espeak voice with Kokoro.

## Current Status

The repository was created in August 2026 and last updated in September 2026, with active recent pushes. It carries an MIT license, 7 stars, and 3 forks at the time of indexing. The project is in active development with open issues at zero.

## Features
- Read Claude Code replies aloud via speaker button, hotkey, or slash command
- Free system TTS (macOS say, Linux speech-dispatcher, Windows SAPI) with zero setup
- Kokoro local neural voice with 54 voices, no account required
- Support for Speechify, ElevenLabs, and OpenAI TTS APIs via environment variable keys
- Custom command provider for any local TTS engine (e.g., Piper)
- Chunked playback: audio starts in 1–3 seconds regardless of reply length
- Auto-read mode for every reply (off by default)
- VS Code status-bar button, toolbar icon, and keyboard shortcuts (Ctrl+Alt+S / Ctrl+Alt+X)
- Right-click 'Read aloud' context menu on highlighted text
- In-chat speaker button beside the Claude Code microphone
- Settings panel and searchable voice picker inside Claude's sidebar
- Code blocks announced as 'code omitted' to avoid reading JSON aloud
- Stop playback mid-sentence via command, button, or hotkey
- Config stored at ~/.config/claude-read-aloud/config.json

## Integrations
Claude Code, VS Code, Kokoro (local neural TTS), Speechify API, ElevenLabs API, OpenAI TTS API, Piper (local TTS engine), macOS say, Linux speech-dispatcher, Windows SAPI

## Platforms
WINDOWS, MACOS, LINUX, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/MichaelPGifford/claude-read-aloud
- Documentation: https://github.com/MichaelPGifford/claude-read-aloud#readme
- Repository: https://github.com/MichaelPGifford/claude-read-aloud
- EveryDev.ai: https://www.everydev.ai/tools/claude-read-aloud