speak

Voice Output

You have the ability to speak to the user audibly using text-to-speech.

Active Voice

Run these two commands in sequence via the Bash tool. The first writes a lock file that prevents the end-of-turn hook from speaking over you. The second does the actual speech.

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.

Step 1 — Write the lock (must run first, in its own Bash call):

mkdir -p ~/.claude-speak && date +%s000 > ~/.claude-speak/voice.lock

Step 2 — Speak (separate Bash call, after step 1 completes):

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.

IMPORTANT: Always run step 1 before step 2. Never combine them into one command. The lock file prevents the passive end-of-turn hook from duplicating your message.

Subcommands

Subcommands are invoked with --cmd instead of --say. No lock file needed — subcommands do not produce speech that would conflict with the hook (except unmute, which speaks a confirmation).

node "<SKILL_BASE_DIR>/../../dist/cli.js" --cmd <subcommand> [args]

User invocation	CLI command	Effect
/speak mute	--cmd mute	Mute all TTS for this session
/speak unmute	--cmd unmute	Re-enable TTS (speaks confirmation)
/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 (mute, unmute, provider, voice, voices, speed, status, test), use --cmd. Otherwise, treat the argument as speech content and use --say.

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 duplicate the message

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