Narrator - Voice Output Plugin for Claude Code
A Claude Code plugin that speaks responses aloud using Kokoro TTS, a local neural text-to-speech engine. No cloud APIs, no latency — everything runs on your machine.
Prerequisites
- Python 3.9+ (tested on 3.13)
- macOS or Linux with audio output (speakers or headphones)
- Claude Code CLI
Installation
From GitHub (recommended)
In Claude Code, run these slash commands:
-
Add the marketplace:
/plugin marketplace add shreyas-s-rao/claude-code-narrator
-
Install the plugin:
/plugin install narrator
-
Reload:
/reload-plugins
Linux note: If /tmp is a separate filesystem (tmpfs), plugin installation may fail with EXDEV: cross-device link not permitted. Fix by setting TMPDIR before launching Claude Code:
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
Then run the install commands above in that session. This is a Claude Code platform limitation, not specific to this plugin.
From local directory
If you've cloned the repo locally:
-
Add the marketplace:
/plugin marketplace add /path/to/claude-code-narrator
-
Install and reload as above
Direct plugin loading (development)
claude --plugin-dir /path/to/claude-code-narrator
Getting Started
- Enable narrator: Type
/narrator:on in Claude Code
- Kokoro TTS and all dependencies are automatically installed into a dedicated venv (
~/.claude-narrator-venv) on first run. This takes a few minutes.
- Once installed, the narrator speaks tool steps and responses aloud.
- Change voice:
/narrator:cast af_bella (or any voice from the table below)
- Silence:
/narrator:hush to stop current speech, /narrator:off to disable entirely
Commands
| Command | Description |
|---|
/narrator:on | Enable voice output (auto-installs Kokoro on first run) |
/narrator:off | Disable voice output |
/narrator:cast [voice] | Change voice or list available voices |
/narrator:speed [value] | Change speech speed (0.5–2.0, default 1.1) |
/narrator:speak [text] | Speak on demand, even if narrator is off |
/narrator:hush | Silence all current and queued speech |
All commands accept --local to apply settings to the current directory only (see Per-Directory Config).
Available Voices
| Voice | Gender | Description |
|---|
af_heart | Female | Warm, expressive (default) |
af_bella | Female | Clear, professional |
af_nicole | Female | Soft, gentle |
af_sarah | Female | Bright, energetic |
af_sky | Female | Calm, composed |
am_adam | Male | Deep, authoritative |
am_michael | Male | Warm, friendly |
am_fenrir | Male | Bold, commanding |
What Gets Spoken
| Event | What you hear |
|---|
| Tool use (Read, Write, Bash, etc.) | Short description, e.g. "Reading file settings dot json" |
| Text between tool calls | The assistant's intermediate commentary |
| Final response | First ~1000 characters, ending at a sentence boundary |
| Notification | Title and message from Claude Code notifications |
| User input | Speech is automatically silenced when you type or click |
Per-Directory Config
You can override narrator settings per directory, which is useful when running multiple Claude Code sessions with different voices.
/narrator:on --local # enable narrator in this directory only
/narrator:cast --local am_adam # use a different voice in this directory
/narrator:speed --local 1.5 # use a different speed in this directory
/narrator:off --local # disable narrator in this directory only
Local settings are stored in <cwd>/.claude-code-narrator/config. Only the keys you set locally are overridden — missing keys fall back to the global config at ~/.claude-code-narrator/config.
Add the local config file to your .gitignore so it's not committed:
echo .claude-code-narrator >> .gitignore
Multi-Session Behavior
All sessions share a single daemon and FIFO (sequential playback, no overlap). Each session's utterances carry their own voice and speed settings, so if session A uses am_adam and session B uses af_bella, utterances interleave with the correct voices.
Documentation
Development
To work on the plugin locally, clone the repo and load it:
git clone https://github.com/shreyas-s-rao/claude-code-narrator
