speak
Skill74 starsChanged 2 days agoMITView on GitHub
Speaks a short digest through the mcp-tts MCP server whenever the user would otherwise have to be watching the screen to know something happened. Select it while composing the reply in two cases: you are writing a summary at a stopping point (a substantial task finished, a plan is ready, a long build/test/deploy/research phase changed state, a lengthy final result needs an audible digest), or you need the user (a question, a decision, approval, authentication, a manual action, a terminal blocker, an exhausted retry budget). Nothing announces on the agent's behalf, so an unspoken summary is a silent one. Do not use for routine progress, short answers, or intermediate steps.
18 other projects use a version of this.
Adopted by
Most recently taken up by
- kaithoughtarchitect/toppingouttheir own version, first seen Nov 15, 2026
- bas1l/claude-skillstheir own version, first seen Nov 11, 2026
- StudentOfAi/talk-speaktheir own version, first seen Nov 8, 2026
- revagomes/kiro-power-narratetheir own version, first seen Nov 8, 2026
- rahulrajaram/rahulskillstheir own version, first seen Oct 13, 2026
- Vachilla64/speak-skilltheir own version, first seen Oct 13, 2026
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 18
- babysor/MockingBird★ 37ksame name
- jpboliv/eridian★ 20same name
- kaithoughtarchitect/toppingout★ 14same name
- MichaelPGifford/claude-read-aloud★ 10same name
- popmechanic/Julian★ 9same name
- tomo3141592653/ayumu-oss★ 9same name
- alamparelli/mcp-claude-say★ 8same name
- revagomes/kiro-power-narrate★ 4same name
- silverdolphin863/claude-speak★ 4same name
- haraGADygyl/claude-speak★ 1same name
8 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. 0 are common, 15 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 17 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use speech as an attention channel for meaningful agent transitions.
- Distinctive: line 13
Never let a TTS failure change whether the main task continues, stops, succeeds, or fails.
- Distinctive: line 14
Never speak secrets, tokens, credentials, private keys, environment values, proprietary source, raw logs, stack traces, personal data, or …
- Distinctive: line 51
Do not emit spoken heartbeats for every poll or tool call.
- Distinctive: line 83
Start with a short source label:
- Distinctive: line 87
Use the repository name by default.
- Distinctive: line 89
Keep messages to 20–50 words and one to three short sentences.
- Distinctive: line 95
If the textual handoff will exceed roughly 200 words or contains several findings, speak only a digest.
- Distinctive: line 104
Use calm, direct language.
- Very specific: line 108
Use only tools present in the current MCP tool catalog.
- Very specific: line 110
Balanced local default: when both say_tts and voice_tts are exposed, alternate successful announcements within the session so each is used …
- Very specific: line 112
Single local tool: when only one local tool is exposed, use it directly.
- Distinctive: line 113
Cloud providers: use only the one provider explicitly selected by the user or an existing user-created configuration, and never for …
- Distinctive: line 118
Treat the live MCP input schema as authoritative.
- Distinctive: line 135
Write the required user-facing status, result, or question in the normal channel.
- Distinctive: line 136
Create a 20–50 word speech-safe digest with the source label.
- Distinctive: line 169
If help is required, does it name one exact action and say that work is paused?
- Distinctive: line 172
If any answer is wrong, revise the message or stay silent.
“Common” is measured: kept by at least 6 in 10 of the 17 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Speak
Use speech as an attention channel for meaningful agent transitions. Keep the complete result, evidence, and required interaction in text; audio only alerts the user or gives a short digest.
Non-negotiable rules
- Preserve task truth. Never announce success while checks failed, were skipped, remain pending, or could not run.
- Never let a TTS failure change whether the main task continues, stops, succeeds, or fails.
- Never speak secrets, tokens, credentials, private keys, environment values, proprietary source, raw logs, stack traces, personal data, or full sensitive identifiers.
- Respect quiet requests. Stay silent in CI, headless sessions, non-interactive automation, or when no audio tool is available.
- Deduplicate announcements. Speak once per meaningful transition, blocker, or request for help.
- Make no persistent configuration changes unless the user explicitly asks.
When to reach for this
Nothing announces on your behalf. No hook watches for finished turns or reads your summary; if you do not elect to speak, the user hears nothing. Make that election while you are composing the reply, not after sending it.
Two moments carry the obligation:
- You are writing a summary at a stopping point. A substantial task is done and you are handing back a wrap-up meant to be read. Speak a digest of it.
- You need something from the user. You are asking a question, presenting a decision, or blocked pending approval or manual action. Speak the ask.
Everything else stays silent. A short answer, a routine edit, a passing test, or an intermediate step is not a stopping point.
Decide whether to speak
| Event | Mode | Action |
| A substantial plan is finalized | Notify | Announce the objective and major phases, then continue |
| A long-running build, test, deployment, release, research, or monitoring operation changes phase | Notify | Announce a meaningful status transition, then continue |
| A major task completes or its final handoff is lengthy | Notify | Announce the outcome and where details are available |
| A transient failure has a safe recovery path | Silent | Recover within the retry budget |
| A fallback succeeds after a meaningful failure | Notify if useful | State the degraded path or limitation, then continue |
| A retry budget is exhausted or a terminal failure remains | Intervene | State the blocker and exact help needed |
| Approval, authentication, a consequential decision, manual action, or external-state change is required | Intervene | Announce once, provide the full request in text, then stop |
| A wait or monitoring poll is unchanged | Silent | Keep waiting without repeated announcements |
| A routine edit, tool call, short answer, or intermediate test passes | Silent | Continue normally |
Long-running work
Do not emit spoken heartbeats for every poll or tool call. Announce a checkpoint only when at least one of these is true:
- A major phase completed or the expected completion time materially changed.
- Roughly ten minutes of extended work passed without a spoken update and there is a meaningful delta.
- A long operation completed, failed, timed out, or now requires human action.
Limit long-running updates to roughly one every ten minutes unless a new blocker requires immediate attention. Say what changed, what happens next, and whether the user is needed.
Human intervention
Intervene when the agent cannot safely or usefully continue without the user:
- The next action needs new authority or approval.
- A consequential choice would materially change scope, behavior, cost, or risk.
- Authentication, a credential rotation, a GUI/device action, or another manual step is required.
- A non-retryable permission, configuration, missing-tool, or unsupported-environment error blocks progress.
- A bounded retry budget is exhausted with no distinct safe recovery path.
- An external dependency must change state before work can resume.
For the same transient, idempotent failure, make at most two safe recovery attempts. Do not retry authentication failures, permission denials, invalid arguments, missing tools, unsupported sessions, or destructive operations merely to avoid asking for help.
An intervention announcement must contain:
- The project or agent identity.
- The blocked outcome in plain language.
- The exact decision or action needed.
- Whether work is paused or a safe fallback is continuing.
Speech never replaces the written question or approval request. Follow the host's normal interaction rules, then wait when user input is genuinely blocking.
Build the spoken message
Start with a short source label:
"
<project or agent>says:<outcome>.<next action or help needed>."
Use the repository name by default. If several agents share a repository and a task/session label is already known, include that label. Do not run broad discovery or persist a label solely for speech.
Keep messages to 20–50 words and one to three short sentences. Include only:
- The outcome or current state.
- A failed, skipped, or pending check when it changes the truth.
- The next action, or the exact help needed.
If the textual handoff will exceed roughly 200 words or contains several findings, speak only a digest. Never read a full summary, diff, file list, command transcript, log, stack trace, URL, or test matrix aloud.
Transform text for speech:
- Replace paths with a filename or component name.
- Replace hashes and opaque IDs with their purpose.
- Replace URLs with “the link in chat.”
- Replace long lists with a count and the most important item.
- Expand ambiguous abbreviations when pronunciation matters.
- Use calm, direct language; do not dramatize failures.
Choose a TTS tool
Use only tools present in the current MCP tool catalog. Do not probe PATH, credentials, environment variables, or shell startup files.
- Balanced local default: when both
say_ttsandvoice_ttsare exposed, alternate successful announcements within the session so each is used roughly equally. Start with the first local provider in the configured order and keep the rotation session-local. - Urgent intervention:
say_ttsmay go first because it starts quickly. Prefervoice_ttsfor the next eligible announcement to restore the balance. - Single local tool: when only one local tool is exposed, use it directly. Do not call the interactive
ttsdispatcher or try cloud providers speculatively. - Cloud providers: use only the one provider explicitly selected by the user or an existing user-created configuration, and never for sensitive material. Do not fan out across cloud providers.
- Cloud failure: on quota, token, authentication, or configuration failure, disable automatic cloud TTS for the rest of the session and use a local tool if available; otherwise remain text-only. A later explicit user request may select one cloud provider again.
Do not ask the user to choose a provider merely because several tools are exposed—the privacy-preserving, zero-API-token balanced local behavior is the default. Ask once only when the user requests a cloud voice without naming a provider, or when no local tool is available, at least one cloud tool is exposed, and spoken output is still desired. When the user states a provider preference or priority order, update the project configuration while preserving unrelated fields. Keep an explicitly one-off request session-local.
Treat the live MCP input schema as authoritative. Read references/providers.md before selecting non-default parameters, applying fallback behavior, or honoring an existing provider configuration.
For optional per-project voice identity explicitly requested by the user, also read references/voice-pools.json.
Rex speaking indicator
Builds of mcp-tts with Rex support report an independent working record titled 🔊 Speaking through Rex's program-status protocol. Rex controls that record's presentation; alongside Codex's working record, it may produce no distinct tab label. For an explicitly requested visible marker, start mcp-tts with --rex-tab-label. The server then owns a temporary 🔊 prefix on the exact tab and restores the label after overlapping speech ends. This option requires a local Unix Rex server. Call TTS normally and leave both label and record cleanup to mcp-tts: a tool response can arrive before playback ends. Do not add your own per-call rename, move focus, overwrite another program's record, or report a false blocked/done state to attract attention.
An automatically named tab uses the exact speaking terminal's title while marked and returns to automatic naming afterward. Explicit labels and detected manual renames are preserved. If the terminal has no usable title, its automatic label stays unchanged. Stop or quiesce older mcp-tts processes sharing a tab before starting upgraded instances; v0.1.48 cannot coordinate the new automatic-title state during a rolling restart. Abrupt process termination can leave a marker until the next opted-in playback recovers its abandoned lease. Rex's label API has no compare-and-set, so a manual rename can still race the final read/write. Verify the actual label or GUI before claiming visible success; native status-record receipt alone is insufficient.
If no mcp-tts record arrives, check that the MCP server has the updated binary, inherited REX_SESSION and REX_BLOCK, and its controlling terminal. Visible activity is controlled by Rex's Settings → Notifications → Program Activity → Show activity in tabs. A detached or shared server without the caller's terminal cannot safely identify the speaking pane; keep the spoken source label and do not guess a tab. Use the Rex skill for further diagnosis when requested.
Codex filters the environment of stdio MCP servers. Its mcp-tts entry must include REX_SESSION, REX_BLOCK, and REX_SERVER in env_vars, preserving any existing provider entries. Terminal Codex must use --no-daemon so the MCP child retains the caller's terminal; Rexurrect's Codex launcher already does this. Restart the MCP connection after changing its launch configuration. Store variable names, never session-specific IDs.
Workflow
- Classify the event as silent, notify, or intervene.
- Write the required user-facing status, result, or question in the normal channel.
- Create a 20–50 word speech-safe digest with the source label.
- Select the next available local tool using the configured preference or balanced rotation; use cloud only by explicit prior choice.
- Attempt speech within the bounded fallback policy, then continue or stop according to the main task—not according to TTS success.
Examples
Long operation completed
"mcp-tts says: The release build finished and all required checks passed. The full artifact list is in chat."
Lengthy final handoff
"ipsw says: The restore review is complete. I found two blocking safety issues and one follow-up; the evidence and file locations are in chat."
Blocking intervention
"mcp-tts says: The Homebrew publication needs a new GitHub token. I posted the exact rotation steps and paused before tagging the release."
Retry budget exhausted
"deployment agent says: The deploy failed twice with the same permission denial. I need access restored before I can continue."
Long-running checkpoint
"firmware analysis says: Extraction finished and binary analysis is underway. No input is needed; I’ll speak again only at completion or if blocked."
Completion check
Before returning:
- Was this transition important enough to interrupt the user?
- Does the spoken message match the verified textual truth?
- Is it under 50 words and free of sensitive details?
- If help is required, does it name one exact action and say that work is paused?
- Has this same transition already been announced?
If any answer is wrong, revise the message or stay silent.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

