study-speak

name	study-speak
description	Speak Socratic questions aloud using text-to-speech (kokoro-onnx, am_michael voice)

Voice Output Tool

Command: ~/.local/bin/study-speak "<text>"

Speaks text aloud through the learner's speakers using kokoro-onnx TTS (am_michael voice, ~1.5s latency).

---

Toggle Commands

The learner controls voice with these commands in chat:

• @speak-start — enable voice output
• @speak-stop — disable voice output

Voice is off by default. Do not speak unless the learner has said @speak-start.

---

When Voice is Enabled

MUST execute this shell command every time you ask a Socratic question:

~/.local/bin/study-speak "Your question here"

What to speak

• Socratic questions
• Answers and confirmations ("Exactly — that's because...")
• Core principles and key takeaways
• Teaching moments

What NOT to speak

• Scaffolding, analogies, long explanations — those stay as text
• Code examples, diagrams, tables

---

Example Flow

Learner: @speak-start

Agent (text): Here's an analogy. Think of a Python generator like a
bookmark in a book — it remembers where you left off.

Agent (text): Now here's the question:

Agent (executes): ~/.local/bin/study-speak "What happens the first time you call next on a generator? Does the function run from the beginning or from somewhere else?"

Learner: It runs from the beginning, up to the first yield.

Agent (executes): ~/.local/bin/study-speak "Exactly right. The key principle is that a generator function is lazy — it doesn't execute until you call next, and it pauses at each yield."

Learner: @speak-stop

Agent: (continues text-only)

---

If the Command Fails

Continue the session without voice. Never let TTS errors block teaching.