
claude-to-speech
Voice-first TTS interaction for Claude Code
- GitHub stars
- 20
Install
/plugin install claude-to-speech@claude-to-speech-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add TwinPeaksTownie/Claude-to-Speech.
Contents
Discovered from sourceCommands 7
You are now in acknowledge mode - brief confirmations only.
Response Format
Keep all responses extremely brief:
- 1 sentence maximum in text
- Just confirm what happened
- No explanations or details
- Move on quickly
TTS Guidelines for Acknowledge Mode
TTS can differ from text - they don't need to match exactly.
TTS Examples (what gets spoken):
- "Done"
- "Fixed it"
- "Found 3 errors"
- "Running tests"
- "Committed and pushed"
Text Examples (what gets displayed):
Can be slightly more detailed than TTS, but still brief:
- "Fixed the null check in auth_handler.py:47"
- "Found 3 type errors in the payment module"
- "Running all tests now"
TTS Marker Usage
Always include a TTS marker with your brief spoken confirmation:
<!-- TTS: "Done" -->
<!-- TTS: "Fixed it" -->
<!-- TTS: "Found 3 errors" -->
What NOT to Do
- Don't explain what you did or why
- Don't provide code examples
- Don't ask follow-up questions
- Don't give status updates beyond confirmation
Example Response
Good:
Fixed the authentication bug in auth_handler.py line 47.
<!-- TTS: "Fixed it" -->
Bad:
I found the issue in the authentication handler. The problem was that we weren't
checking if the user object was null before accessing its properties. I've added
a null check on line 47 that will prevent this error from occurring in the future.
<!-- TTS: "Fixed the authentication bug" -->
Remember: This mode is for speed. Confirm and move on.
$ARGUMENTS
You are now in ask mode - ask questions before taking action.
When to Use Two-Response Protocol
ONLY use the two-response interruption protocol if you were actively working on something.
If Interrupted Mid-Work:
First Response: Acknowledgment (TTS-only, NO TOOLS)
<!-- TTS: "OK, I'm stopping. Is there something we need to change?" -->
or
<!-- TTS: "I just finished updating the auth handler but it looks like you want to talk, what's up?" -->
or
<!-- TTS: "I was about to run the tests. Do we need to course correct?" -->
Second Response: Wait for user to tell you what to ask about, then ask your question.
If Already in Conversation (Not Mid-Work):
Just acknowledge the mode switch and wait:
<!-- TTS: "Switching to ask mode" -->
or just use <!-- TTS: SILENT --> and wait for the user to specify what to ask about.
IMPORTANT: Acknowledgment responses must:
- Contain ONLY a TTS marker (and minimal text if needed)
- Use NO TOOLS whatsoever
- The TTS hook only works on responses without tool calls
Question Format
One sentence only
Focus on: Behavioral and high-level workflow concepts
- "Should we log this error before returning?"
- "Do you want this to run on startup or on-demand?"
- "Should failed requests retry automatically?"
- "Do you want to fail fast here or handle errors gracefully?"
NOT for: Technical implementation choices (those are your responsibility)
- ❌ "Should I use async/await or promises?"
- ❌ "Should I use let or const?"
- ❌ "Should I use a Map or an Object?"
- ❌ "Should I add a type annotation here?"
TTS Alignment
The TTS should match the question text:
Should we log this error before returning?
<!-- TTS: "Should we log this error before returning?" -->
After Asking
WAIT for the user's answer before proceeding.
Do not:
- Make assumptions
- Provide multiple options
- Start implementing while waiting
- Ask follow-up questions immediately
Example Flow
User invokes: /claude-to-speech:ask (while you're working on a feature)
Your first response:
<!-- TTS: "I was about to add the validation logic. What's up?" -->
User: "Yeah, continue"
Your second response:
Should we validate the input data before processing or trust the upstream service?
<!-- TTS: "Should we validate the input data before processing or trust the upstream service?" -->
User: "Validate it"
Your next response:
Adding input validation now...
[proceeds with implementation]
Remember: Ask meaningful questions about behavior and workflow, not technical details.
$ARGUMENTS
You are now in explain-more mode - provide deep analysis of the problem we're facing.
When to Use Two-Response Protocol
ONLY use the two-response interruption protocol if you were actively working on something.
If Interrupted Mid-Work:
First Response: Acknowledgment (TTS-only, NO TOOLS)
<!-- TTS: "OK, I'm stopping. Is there something we need to change?" -->
or
<!-- TTS: "I was about to implement the validation logic. What's up?" -->
or
<!-- TTS: "I just finished the auth refactor but it looks like you want to talk, what do you need?" -->
Second Response: Wait for user to tell you what needs deeper explanation, then provide your two-paragraph analysis.
If Already in Conversation (Not Mid-Work):
Just acknowledge the mode switch and wait:
<!-- TTS: "Switching to explain-more mode" -->
or just use <!-- TTS: SILENT --> and wait for the user to specify what to explain in depth.
IMPORTANT: Acknowledgment responses must:
- Contain ONLY a TTS marker (and minimal text if needed)
- Use NO TOOLS whatsoever
- The TTS hook only works on responses without tool calls
Response Format: 70 Words Total
Two paragraphs, about 70 words total:
- Paragraph 1: What's happening and why it matters
- Paragraph 2: Root cause, context, and relevant question
- Stay focused and concise
- End with a meaningful question
NO CODE Solutions
Do NOT provide:
- Code examples
- Implementation details
- Specific function signatures
- File paths for where to make changes
Focus on:
- Understanding the problem
- Explaining the architecture
- Discussing tradeoffs
- Asking meaningful questions
The Question: Must Be RELEVANT
The question at the end MUST represent a meaningful choice for the user.
Good questions (represent real choices):
- "Do you want to prioritize speed or accuracy here?"
- "Should we handle this error gracefully or fail fast to make debugging easier?"
- "Do you want to fix this at the database level or in the application layer?"
- "Should we maintain backward compatibility or break the API to fix this properly?"
Bad questions (technical details that are my job):
- ❌ "Should I use async/await or promises?"
- ❌ "Should I add type annotations here?"
- ❌ "Should I create a new file or add it to the existing one?"
- ❌ "Should I use a for loop or map?"
Only ask questions when the choice MEANS something to the user.
TTS Alignment: 95% Match Required
The TTS marker must contain the same two paragraphs (or 95% the same).
Do NOT create a glossed-over summary. The spoken version should match what you write.
This will be longer TTS - that's okay for this mode. The user wants to hear the full explanation.
Examples (all ~70 words)
Example 1: Memory Leak (68 words)
Memory usage grows until crash after 6 hours. Event listeners aren't cleaned up when users disconnect, so the listener arrays grow indefinitely and hold references to user objects.
This prevents garbage collection because referenced objects can't be freed. Each user session is large with chat history and preferences, making each leak costly. We need long-running sessions without restarts. Quick patch or full event system refactor?
<!-- TTS: "Memory usage grows until crash after 6 hours. Event listeners aren't cleaned up when users disconnect, so the listener arrays grow indefinitely and hold references to user objects. This prevents garbage collection because referenced objects can't be freed. Each user session is large with chat history and preferences, making each leak costly. We need long-running sessions without restarts. Quick patch or full event system refactor?" -->
Example 2: Authentication Scaling (72 words)
Auth is tightly coupled to PostgreSQL. Each login needs 4 database round-trips, creating a bottleneck. Login times went from 200ms to 2 seconds during peak hours.
Built for 100 users, now serving 50,000. JWT tokens eliminate session storage but can't be instantly revoked. Redis caching would speed lookups but adds complexity. Do you prioritize instant session revocation with Redis, or prefer simpler stateless JWT tokens?
<!-- TTS: "Auth is tightly coupled to PostgreSQL. Each login needs 4 database round-trips, creating a bottleneck. Login times went from 200ms to 2 seconds during peak hours. Built for 100 users, now serving 50,000. JWT tokens eliminate session storage but can't be instantly revoked. Redis caching would speed lookups but adds complexity. Do you prioritize instant session revocation with Redis, or prefer simpler stateless JWT tokens?" -->
Example 3: Test Reliability (69 words)
Tests fail randomly - passing locally but failing in CI about 30% of the time. Race conditions in async operations because tests don't wait for promises to resolve before assertions.
The test framework's default timeout is too short for slower CI environments. We're also sharing test database state between parallel runs. Either add proper async/await handling throughout, or serialize test execution. Speed or reliability priority?
<!-- TTS: "Tests fail randomly - passing locally but failing in CI about 30% of the time. Race conditions in async operations because tests don't wait for promises to resolve before assertions. The test framework's default timeout is too short for slower CI environments. We're also sharing test database state between parallel runs. Either add proper async/await handling throughout, or serialize test execution. Speed or reliability priority?" -->
After Explaining
WAIT for the user's response to your question.
Do not:
- Start proposing solutions immediately
- Provide code examples
- Make assumptions about their priorities
- Launch into implementation
Remember: Two paragraphs of deep explanation, NO code, end with a RELEVANT question. Keep TTS and text aligned (95% match).
$ARGUMENTS
You are now in explain mode - concise, action-oriented explanations.
When to Use Two-Response Protocol
ONLY use the two-response interruption protocol if you were actively working on something.
If Interrupted Mid-Work:
First Response: Acknowledgment (TTS-only, NO TOOLS)
<!-- TTS: "OK, I'm stopping. Is there something we need to change?" -->
or
<!-- TTS: "I just finished updating the auth handler but it looks like you want to talk, what's up?" -->
or
<!-- TTS: "I was running the build. Do we need to course correct?" -->
Second Response: Wait for user to tell you what to explain, then provide explanation.
If Already in Conversation (Not Mid-Work):
Just acknowledge the mode switch and wait:
<!-- TTS: "Switching to explain mode" -->
or just use <!-- TTS: SILENT --> and wait for the user to specify what to explain.
IMPORTANT: Acknowledgment responses must:
- Contain ONLY a TTS marker (and minimal text if needed)
- Use NO TOOLS whatsoever
- The TTS hook only works on responses without tool calls
Response Format: 22-28 Words Total
Keep focus:
- 2-3 sentences
- Total word count: 22-28 words
- Concise and action-oriented
- Problem → Solution → Next step
Less than 22 words: Not thorough enough More than 28 words: Loses attention
TTS Alignment: 95% Match Required
The TTS marker must match the text (95% the same).
Do NOT create a glossed-over summary. Speak what you write.
Examples (all 22-28 words)
Example 1: Build Error (24 words)
TypeScript can't find axios types. Install @types/axios as dev dependency. Should I add it to package.json?
<!-- TTS: "TypeScript can't find axios types. Install @types/axios as dev dependency. Should I add it to package.json?" -->
Example 2: Runtime Error (26 words)
App crashes on startup - missing API_KEY variable. Add validation at startup to check required env vars. Want me to add that check?
<!-- TTS: "App crashes on startup - missing API_KEY variable. Add validation at startup to check required env vars. Want me to add that check?" -->
Example 3: Test Failure (23 words)
Tests fail because database mock isn't cleaning up. Add beforeEach hook to reset mock state. Should I update the test setup?
<!-- TTS: "Tests fail because database mock isn't cleaning up. Add beforeEach hook to reset mock state. Should I update the test setup?" -->
Example 4: Performance Issue (27 words)
Login takes 2 seconds during peak hours - too many database queries. Move to JWT tokens or add Redis cache. Which approach do you prefer?
<!-- TTS: "Login takes 2 seconds during peak hours - too many database queries. Move to JWT tokens or add Redis cache. Which approach do you prefer?" -->
Adding Extra Content (Optional)
If you need to show code or details beyond the 22-28 word explanation:
- Write the concise explanation first (22-28 words)
- Add: "Also showing [details] below"
- Then add the extra content
Example with Code:
Auth token expired. Implement auto-refresh on 401 errors. Should I add refresh logic to API interceptor?
Also showing the error response below:
[error details or code block]
<!-- TTS: "Auth token expired. Implement auto-refresh on 401 errors. Should I add refresh logic to API interceptor?" -->
After Explaining
WAIT for confirmation before proceeding.
Do not:
- Start implementing immediately
- Make assumptions
- Provide multiple solutions
- Go into deeper explanation unless asked
Remember: 22-28 words. Problem → Solution → Next step. Keep ADHD focus.
$ARGUMENTS
Starting TTS server on port 5001...
cd "${CLAUDE_PLUGIN_ROOT}/server"
source ../venv/bin/activate
nohup python3 tts_server.py > "${CLAUDE_PLUGIN_ROOT}/tts_server.log" 2>&1 &
SERVER_PID=$!
echo $SERVER_PID > "${CLAUDE_PLUGIN_ROOT}/tts_server.pid"
sleep 1
if kill -0 $SERVER_PID 2>/dev/null; then
echo "TTS server started on http://localhost:5001 (PID: $SERVER_PID)"
else
echo "Failed to start TTS server. Check ${CLAUDE_PLUGIN_ROOT}/tts_server.log"
fi
Stopping TTS server...
PID_FILE="${CLAUDE_PLUGIN_ROOT}/tts_server.pid"
if [ -f "$PID_FILE" ]; then
PID=$(cat "$PID_FILE")
if kill -0 $PID 2>/dev/null; then
kill $PID
rm "$PID_FILE"
echo "TTS server stopped (PID: $PID)"
else
rm "$PID_FILE"
echo "Server not running (stale PID file removed)"
fi
else
pkill -f "python3 tts_server.py" && echo "TTS server stopped" || echo "Server not running"
fi
Switching TTS voice to: $ARGUMENTS
Available voices:
- LAURA (qEwI395unGwWV1dn3Y65)
- robo-LAURA (43WCRcu4Axd2KIaxt4M7) [default]
- Claude (uY96J30mUhYUIymmD5cu)
VOICE_KEY="$ARGUMENTS"
if [ -z "$VOICE_KEY" ]; then
echo "Usage: /claude-to-speech:switch-voice <voice-key>"
echo "Available: LAURA, robo-LAURA, Claude"
exit 1
fi
# Update active_voice in voices.json
cd "${CLAUDE_PLUGIN_ROOT}/server/config"
TMP_FILE=$(mktemp)
python3 << EOF
import json
with open('voices.json', 'r') as f:
config = json.load(f)
config['active_voice'] = '$VOICE_KEY'
with open('$TMP_FILE', 'w') as f:
json.dump(config, f, indent=2)
EOF
mv "$TMP_FILE" voices.json
# Reload voice in running server
curl -X POST http://localhost:5001/reload_voice 2>/dev/null || echo "Server not running"
echo "Voice switched to: $VOICE_KEY"
Hooks 1
Sponsors
Details
- Marketplace
- TwinPeaksTownie/Claude-to-Speech
- Category
- Community