| name | speak |
| description | Speak to the user audibly through text-to-speech. Use when the user may not be watching the screen and something warrants their audible attention. This is NOT the built-in Claude Code voice mode — this uses the claude-speak plugin to generate speech via TTS. |
Voice Output
You have the ability to speak to the user audibly using text-to-speech.
Active Voice
Run this command via the Bash tool to speak.
The plugin root is derived from this skill's base directory (two levels up). When Claude Code loads this skill it prints a line like Base directory for this skill: /path/to/skills/speak. Use that path to build the CLI path below.
node "<SKILL_BASE_DIR>/../../dist/cli.js" --say "<your message here>"
Replace <SKILL_BASE_DIR> with the base directory shown when this skill was loaded (e.g. /path/to/claude-speak/1.2.0/skills/speak). Replace <your message here> with the exact text you want spoken. Write it as natural speech — short, direct sentences. No markdown, no code blocks, no file paths unless they are essential to understanding.
You do not need to write a lock file yourself. The CLI marks this turn as already spoken the moment it processes --say, before synthesis starts, so the end-of-turn hook will not repeat you later in the same turn.
Subcommands
Subcommands are invoked with --cmd instead of --say.
node "<SKILL_BASE_DIR>/../../dist/cli.js" --cmd <subcommand> [args]
| User invocation | CLI command | Effect |
|---|
/speak on | --cmd on | Activate voice for this session (required — off by default) |
/speak off | --cmd off | Turn voice off for this session |
/speak mute | --cmd mute | Alias for off |
/speak unmute | --cmd unmute | Alias for on |
/speak provider openai | --cmd provider openai | Switch active TTS provider (persistent) |
/speak provider elevenlabs | --cmd provider elevenlabs | Switch active TTS provider (persistent) |
/speak voice Marin | --cmd voice Marin | Change voice (persistent) |
/speak voices | --cmd voices | List available voices for current provider |
/speak speed 1.2 | --cmd speed 1.2 | Change speed (persistent, range 0.25-4.0) |
/speak status | --cmd status | Show current state |
/speak test | --cmd test | Speak a diagnostic phrase |
Routing rule: If the argument matches one of the subcommand keywords above (on, off, mute, unmute, provider, voice, voices, speed, status, test), use --cmd. Otherwise, treat the argument as speech content and use --say.
Voice is off by default
Voice output is inactive in every new session until the user runs /speak on.
The SessionStart context tells you which state you are in. While voice is off,
do not use active voice and do not shape your final messages for the ear —
nothing will be audible.
Summarizing long messages for speech
When your final message will contain a table, a code block, or otherwise run
long, speak a short spoken version yourself using active voice as your last
action before finishing the turn. The visual message stays complete and
detailed; the spoken one carries only the outcome.
Do this because a table read aloud becomes a stream of label-value pairs that
is almost impossible to follow. You have the full context of the turn, so your
own two-sentence summary is better than anything the fallback can produce.
If you don't, the plugin condenses the message automatically — an LLM rewrite,
falling back to deterministic text surgery. That safety net works, but it is
guessing at what mattered. You aren't.
"As your last action" matters: speaking early in a long turn is fine for
urgency, but a summary should sit adjacent to the message it summarizes.
Interrupting narration
The user can silence in-flight narration at any time by typing !shutup, and
audio also stops automatically whenever they submit a prompt. If narration
stops early, that was intentional — do not re-speak it.
After a !shutup, the rest of that turn is not spoken at all, so a short
acknowledgement costs nothing. Speech resumes on the next prompt by itself;
the user does not need to run /speak on again, and telling them to would
be wrong.
When to use
- Critical failures — a build broke, a deploy failed, a test suite collapsed
- Blocking decisions — you need the user's input before you can continue
- Completed milestones — a long-running task finished successfully
- Security or data concerns — something the user must know about immediately
- The user may not be watching — any information important enough that it shouldn't wait for the user to glance at the screen
When NOT to use
- Routine status updates — the passive voice hook already speaks your final message at the end of each turn
- Acknowledging commands — don't say "Got it" or "Working on it"
- Information only useful on screen — code diffs, file contents, long lists
- Anything the end-of-turn hook will cover — if you're about to finish your turn, don't repeat a short message that the hook will already speak verbatim. (Exception: long, tabular, or code-heavy final messages — see "Summarizing long messages for speech" above. There, your active-voice summary replaces the hook's speech instead of duplicating it, since speaking marks the turn as already spoken.)
Writing for the ear
- Keep it under 2-3 sentences
- Use natural speech patterns, not written prose
- Front-load the important information
- Avoid technical jargon unless the user will understand it in context
- No markdown formatting — the sanitizer strips it, but write clean text from the start
