mac-voice-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-28
+
+### Added
+- **A more natural voice, automatically.** On macOS, speech uses the best Premium or Enhanced voice installed for the spoken language, preferring your Mac's region, and otherwise the system voice. `voice_setup` shows which voice is in use and, if there's no Premium voice, how to download one for free in System Settings. `VOICE_MCP_VOICE=default` keeps the system voice.
+- **A timing line on every turn.** Each `speak_and_listen` result ends with a line like `voice-mcp timing: spoke 3.1 s · listened 4.0 s (user talked 2.2 s) · transcribed 0.3 s`, which makes a slow turn easy to explain. The model is told to ignore it unless you ask.
+- **Claude Code plugin commands and a skill:**
+  - `/mac-voice-mcp:talk [task]` starts a voice conversation. It pre-approves voice turns while it runs.
+  - `/mac-voice-mcp:setup` checks, installs with your OK, and tests.
+  - The `voice-help` skill gives Claude fuller usage guidance and a troubleshooting table.
+- **README: "Allow voice turns without prompts".** The `permissions.allow` entries that stop Claude Code from asking for approval on every voice turn.
+- **Releases:**
+  - `npm version patch|minor|major` now also updates `server.json` and the plugin.
+  - Each tag creates a GitHub Release from this changelog.
+  - Tests fail if any version, the plugin's pinned npm version or the changelog entry is out of sync.
+
+### Changed
+- **The plugin runs the exact npm release it ships with** (`mac-voice-mcp@0.2.0`), instead of whatever version npx cached first.
+- **The README's install configs use `mac-voice-mcp@latest`,** so npx picks up new releases. This covers Claude Desktop, Cursor, VS Code and `claude mcp add`.
+- **The publish workflow is safe to re-run.**
+  - It skips npm and the MCP Registry when the version is already there.
+  - It retries the registry while npm catches up.
+  - It checks out without persisting credentials.
+
+## [0.1.1] - 2026-09-23
+
+### Added
+- **README:** one-click install buttons for Cursor and VS Code, and install steps for the Claude Code plugin marketplace and the official MCP Registry.
+- **Releases publish through npm trusted publishing, with provenance.**
+
+### Changed
+- **Node.js 22 or newer is now required.** Node 18 and 20 no longer receive security fixes. CI tests on Node 22, 24 and 26.
+
+### Fixed
+- **"It's on screen" when it isn't** ([#3](https://github.com/jeet0007/mac-voice-mcp/issues/3)).
+  - When the spoken text sends you to look at something, the model is reminded that only its own message text reaches your screen, not the speech and not Bash/tool output. The speaking rules now say the same.
+  - Thanks to Copilot for the first version ([#4](https://github.com/jeet0007/mac-voice-mcp/pull/4)).
+  - The trigger phrases were narrowed so that ordinary sentences like "above thirty degrees" or "see the doctor" don't set it off.
+
+### Security
+- TruffleHog secret scanning, CodeQL, dependency review, `npm audit` in CI, and Dependabot.
+
+## [0.1.0] - 2026-09-23
+
+### Added
+- First release:
+  - `speak_and_listen`: natural turn-taking, with on-device whisper.cpp and a warm server.
+  - `voice_setup`: checks first, installs only what's missing, and only after you agree.
+  - The `setup` and `voice_mode` prompts.
+
+[Unreleased]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jeet0007/mac-voice-mcp/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/jeet0007/mac-voice-mcp/compare/119a589...v0.1.1
+[0.1.0]: https://github.com/jeet0007/mac-voice-mcp/tree/119a589

package/README.md

@@ -16,7 +16,7 @@
 <p align="center">
   <img alt="Platform: macOS, Apple Silicon" src="https://img.shields.io/badge/platform-macOS%20%C2%B7%20Apple%20Silicon-000000?logo=apple">
   <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-6f42c1"></a>
-  <img alt="Node.js 18+" src="https://img.shields.io/node/v/mac-voice-mcp?logo=node.js&color=339933">
+  <img alt="Node.js 22+" src="https://img.shields.io/node/v/mac-voice-mcp?logo=node.js&color=339933">
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
   <a href="SECURITY.md"><img alt="Dependabot enabled" src="https://img.shields.io/badge/Dependabot-enabled-025e8c?logo=dependabot"></a>
   <a href="#-vibe-coded"><img alt="Vibe-coded with Claude" src="https://img.shields.io/badge/vibe--coded-with%20Claude-d97757"></a>
@@ -59,19 +59,32 @@ The server has **two tools and two prompts**:
 
 ## Install
 
-**1. Add the server to your client.** You need Node.js 18.17 or newer.
+You need **Node.js 22 or newer**. Whichever way you install, run setup once afterwards (see *Then*, below).
 
-**Claude Code**
+### One click
 
-```bash
-claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp
-```
+<p>
+  <a href="https://cursor.com/en/install-mcp?name=voice-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1hYy12b2ljZS1tY3BAbGF0ZXN0Il19"><img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" height="32"></a>
+  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=voice-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mac-voice-mcp%40latest%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white" height="32"></a>
+  <a href="https://insiders.vscode.dev/redirect/mcp/install?name=voice-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mac-voice-mcp%40latest%22%5D%7D&quality=insiders"><img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white" height="32"></a>
+</p>
 
-Or install it as a Claude Code plugin:
+### From a marketplace
 
-```
-/plugin marketplace add jeet0007/mac-voice-mcp
-/plugin install mac-voice-mcp@mac-voice-mcp
+- **Claude Code plugin marketplace.** This repo is its own marketplace:
+  ```
+  /plugin marketplace add jeet0007/mac-voice-mcp
+  /plugin install mac-voice-mcp@mac-voice-mcp
+  ```
+  The plugin adds `/mac-voice-mcp:setup` and `/mac-voice-mcp:talk`, plus a skill that teaches Claude how to use voice well and fix common problems. Each plugin version runs the matching npm release.
+- **The official MCP Registry.** It's listed as [`io.github.jeet0007/mac-voice-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jeet0007/mac-voice-mcp). Apps and directories that read the registry pick it up from there. In VS Code, open the Extensions view (⇧⌘X), search `@mcp mac-voice`, and click **Install**. Smithery, Glama, PulseMCP and mcp.so copy the registry, so it shows up there too.
+
+### By hand
+
+**Claude Code**
+
+```bash
+claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp@latest
 ```
 
 **Claude Desktop.** Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`, then quit (⌘Q) and reopen the app:
@@ -81,27 +94,35 @@ Or install it as a Claude Code plugin:
   "mcpServers": {
     "voice-mcp": {
       "command": "npx",
-      "args": ["-y", "mac-voice-mcp"]
+      "args": ["-y", "mac-voice-mcp@latest"]
     }
   }
 }
 ```
 
+`@latest` makes npx check for a new release each time the app starts. Without it, npx keeps running whichever version it cached first.
+
 If you get `spawn npx ENOENT`, use the full path from `which npx`, e.g. `"command": "/opt/homebrew/bin/npx"`.
 
-**Cursor.** Add the same `mcpServers` block to `~/.cursor/mcp.json`, or use the one-click link:
+**Cursor.** Add the same `mcpServers` block to `~/.cursor/mcp.json`.
 
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=voice-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1hYy12b2ljZS1tY3AiXX0=
+**VS Code.** Run **MCP: Add Server** from the Command Palette, or:
+
+```bash
+code --add-mcp '{"name":"voice-mcp","command":"npx","args":["-y","mac-voice-mcp@latest"]}'
 ```
 
-**2. Run setup once.** Ask Claude to *"set up voice"*. In Claude Code you can also run `/mcp__voice-mcp__setup`, or from a terminal run `npx -y mac-voice-mcp setup`.
+**Any other MCP client.** Run `npx -y mac-voice-mcp@latest` as a stdio server.
+
+### Then: set up and allow the mic
+
+**Run setup once.** Ask Claude to *"set up voice"*. In Claude Code you can also run `/mac-voice-mcp:setup` (plugin) or `/mcp__voice-mcp__setup` (added by hand), or from a terminal run `npx -y mac-voice-mcp@latest setup`.
 
 Setup checks what's already there before it changes anything:
 
 | Needed | Provided by | If it's missing |
 |---|---|---|
-| Voice | macOS `say` | Nothing to do. It's part of macOS. |
+| Voice | macOS `say`, using the most natural voice installed | Nothing to do. For a far better voice, add a free Premium one (see below). |
 | Microphone capture | SoX (`rec`) | `brew install sox` |
 | Speech-to-text | whisper.cpp (`whisper-cli` and `whisper-server`, Metal-accelerated) | `brew install whisper-cpp` |
 | Speech model | `base.en`, ~140 MB | Downloaded once to `~/.cache/mac-voice-mcp/models/` |
@@ -110,7 +131,26 @@ Setup checks what's already there before it changes anything:
 - **Nothing happens without your OK.** Claude calls `voice_setup` to check first, shows you the checklist, and asks before calling it with `install=true`.
 - **Slow installs don't time out.** If `brew install whisper-cpp` takes a while, setup reports INSTALLING. The install carries on in the background, and the next check picks up the result.
 
-**3. Allow the microphone.** The first time Claude listens, macOS asks whether Claude (or Cursor, or your terminal) can use the microphone. Click Allow.
+**Allow the microphone.** The first time Claude listens, macOS asks whether Claude (or Cursor, or your terminal) can use the microphone. Click Allow.
+
+**Get a better voice (recommended).** macOS includes free Premium voices that sound far more natural than the default. Open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, and download one, for example English → *Ava (Premium)* or *Zoe (Premium)*. The next voice turn uses it automatically. To choose a specific voice, or keep the system voice, see `VOICE_MCP_VOICE` under [Configuration](#configuration).
+
+### Allow voice turns without prompts
+
+By default, Claude Code asks for approval every time Claude wants to speak, which breaks the flow of a conversation. To allow voice turns, add the tool to the `permissions.allow` list in `~/.claude/settings.json`. Use the name that matches how you installed it:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_mac-voice-mcp_voice-mcp__speak_and_listen",
+      "mcp__voice-mcp__speak_and_listen"
+    ]
+  }
+}
+```
+
+The first name is for the plugin, the second for `claude mcp add voice-mcp …`. Leave `voice_setup` out, so installs still ask you first. While `/mac-voice-mcp:talk` runs, voice turns are already allowed.
 
 ### Installing from a clone
 
@@ -123,7 +163,7 @@ git clone https://github.com/jeet0007/mac-voice-mcp && bash mac-voice-mcp/instal
 ## Using it
 
 - **"Work on X and check in with me by voice when you need a decision."** Claude works quietly and only speaks at decision points.
-- **`/mcp__voice-mcp__voice_mode fix the flaky login test`.** Claude reads its plan back to you, then checks in at each checkpoint. Say "stop voice mode" or "I'm back" to end it.
+- **`/mac-voice-mcp:talk fix the flaky login test`** (plugin), or **`/mcp__voice-mcp__voice_mode fix the flaky login test`** (added by hand). Claude reads its plan back to you, then checks in at each checkpoint. Say "stop voice mode" or "I'm back" to end it.
 - **"Read me a 20-second summary of this PR and ask if I should approve it."** Use this for one-off briefings.
 - **Just talk after the chime.** You don't need to hurry or fill silence. If you're still talking at the 30-second safety cap (`listen_seconds`), Claude is told your reply may be cut off and asks you to continue.
 
@@ -160,7 +200,7 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 
 | Variable | Default | |
 |---|---|---|
-| `VOICE_MCP_VOICE` | system voice | macOS voice, e.g. `Samantha`, `Daniel`, `Kanya`. List them with `say -v '?'`. |
+| `VOICE_MCP_VOICE` | most natural installed | Unset: the best Premium or Enhanced voice installed for the language, else the system voice. Set a name, e.g. `Ava (Premium)`, `Daniel`, `Kanya` (list them with `say -v '?'`), or `default` to always use the system voice. |
 | `VOICE_MCP_RATE` | system rate | Words per minute, e.g. `200`. |
 | `VOICE_MCP_MAX_SPEAK_WORDS` | `120` | Longer text is cut at a sentence boundary ("the rest is on screen"). |
 | `VOICE_MCP_CHIME` | `1` | Set to `0` to turn off the mic open/close sounds. |
@@ -203,7 +243,7 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 
 | Symptom | Fix |
 |---|---|
-| "voice-mcp is not set up yet" | Ask Claude to *set up voice*, or run `npx -y mac-voice-mcp setup`. |
+| "voice-mcp is not set up yet" | Ask Claude to *set up voice*, or run `npx -y mac-voice-mcp@latest setup`. |
 | "microphone returned pure digital silence" | macOS is blocking the mic for the host app. Go to **System Settings → Privacy & Security → Microphone**, enable Claude / Cursor / your terminal, then restart that app. |
 | No permission prompt ever appears | Run `tccutil reset Microphone <bundle id>` and restart the app. Running `test` in Terminal only gives permission to Terminal, not to Claude Desktop. |
 | It cuts me off while I'm thinking | Set `VOICE_MCP_END_SILENCE_MS=1800` (or up to `2500`). |
@@ -211,6 +251,9 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | It hears its own voice | Use headphones, or turn the speaker volume down. It only listens after it finishes speaking, but echo can linger. |
 | "Homebrew: not installed" | Install it from [brew.sh](https://brew.sh). It needs your password, so it can't run from Claude. Then run setup again. |
 | It garbles names or jargon | Set `VOICE_MCP_WHISPER_PROMPT="Priya, Postgres, Kubernetes"`, or switch to `small.en`. |
+| The voice sounds robotic | Download a Premium voice (see [Get a better voice](#then-set-up-and-allow-the-mic)). It's used automatically. |
+| It asks for approval every turn | Add the tool to Claude Code's allow list: see [Allow voice turns without prompts](#allow-voice-turns-without-prompts). |
+| Turns feel slow | Each result ends with a timing line, e.g. `spoke 3.1 s · listened 4.0 s · transcribed 0.3 s`. Ask Claude what it says. Transcribing should take well under a second. |
 
 ## Known limitations
 
@@ -238,7 +281,7 @@ To report a vulnerability, see [SECURITY.md](SECURITY.md).
 
 ```bash
 npm install
-npm test               # build + 27 tests: unit tests and end-to-end tests over MCP with stub binaries
+npm test               # build + unit tests, end-to-end tests over MCP with stub binaries, and release-metadata checks
 npm run audit          # known-vulnerability and signature checks on dependencies
 npm run setup          # check what's installed; offers to install what's missing
 npm run test:voice     # one real speak → listen → transcribe turn
@@ -255,13 +298,19 @@ npm run inspect        # MCP Inspector
 | `stt.ts` | The warm `whisper-server` with orphan guard, and the `whisper-cli` fallback |
 | `setup.ts` | Requirement checks and consent-based background installs |
 | `voice.ts`, `server.ts`, `index.ts` | The round trip, the MCP tools and prompts, and the CLI |
+| `skills/` | The Claude Code plugin's `/mac-voice-mcp:talk` and `:setup` commands and the `voice-help` skill |
 
 The package installs two commands: `mac-voice-mcp` (the one `npx -y mac-voice-mcp` runs), and `voice-mcp`.
 
 ### Releasing
 
 - **First release:** `bash publish.sh`. It asks before each public step and uses your own GitHub and npm logins. It creates the GitHub repo, publishes to npm, and lists the server in the [official MCP Registry](https://registry.modelcontextprotocol.io), which Smithery, Glama, PulseMCP and mcp.so pick up from.
-- **Later releases:** bump `version` in `package.json` and `server.json`, then push a `v<version>` tag. The Publish workflow tests the build, checks that the tag matches both versions, and publishes to npm and the MCP Registry. It needs no secrets: both logins use GitHub's OIDC identity, once you've set the package's *Trusted Publisher* on npmjs.com (`publish.sh` prints the steps).
+- **Later releases:**
+  1. Add a section to `CHANGELOG.md` for the new version, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format, dated today.
+  2. Run `npm version patch` (bug fixes), `npm version minor` (new features) or `npm version major` (breaking changes), per [semver](https://semver.org). It updates `package.json`, `package-lock.json`, `server.json` and the plugin (including the npm version the plugin runs), commits, and tags `v<version>`.
+  3. Run `git push --follow-tags`.
+
+  The Publish workflow then runs the tests, which also check that every version and the changelog entry match. It publishes to npm with provenance, lists the release in the MCP Registry, and creates a GitHub Release from the changelog section. It needs no secrets: npm and the registry both use GitHub's OIDC identity, once you've set the package's *Trusted Publisher* on npmjs.com (`publish.sh` prints the steps). If a step fails, fix the cause and use **Re-run failed jobs**. Steps that already finished are skipped.
 
 ## License
 

package/dist/audio.js

@@ -15,6 +15,62 @@ export function findTts() {
         return "powershell.exe";
     return which("espeak-ng") ?? which("espeak") ?? which("spd-say");
 }
+/** Parse `say -v '?'` lines such as "Ava (Premium)       en_US    # Hello! My name is Ava." */
+export function parseSayVoices(output) {
+    const voices = [];
+    for (const line of output.split("\n")) {
+        const m = /^(.+?)\s+([a-z]{2,3}_[A-Za-z0-9]+)\s+#/.exec(line.trimEnd());
+        if (!m)
+            continue;
+        const name = m[1].trim();
+        const quality = /\(Premium\)/i.test(name) ? 3 : /\(Enhanced\)/i.test(name) ? 2 : 1;
+        voices.push({ name, locale: m[2], quality });
+    }
+    return voices;
+}
+/**
+ * The most natural installed voice for the language: Premium first, then Enhanced, preferring
+ * the system's region (en_US over en_GB on a US Mac). null = none installed; keep the system voice.
+ */
+export function pickVoice(voices, language, systemLocale) {
+    const lang = (language && language !== "auto" ? language : systemLocale).toLowerCase().split(/[-_]/)[0] ?? "en";
+    const region = (systemLocale.split(/[-_]/)[1] ?? "").toUpperCase();
+    const inRegion = (v) => (region && v.locale.toUpperCase().endsWith(`_${region}`) ? 1 : 0);
+    const candidates = voices.filter((v) => v.quality >= 2 && v.locale.toLowerCase().startsWith(`${lang}_`));
+    candidates.sort((a, b) => b.quality - a.quality || inRegion(b) - inRegion(a) || a.name.localeCompare(b.name));
+    return candidates[0] ?? null;
+}
+export const VOICE_UPGRADE_HINT = "for a much more natural voice, download a Premium one: System Settings → Accessibility → Spoken Content → " +
+    "System Voice → Manage Voices… (for example English → Ava (Premium) or Zoe (Premium)). It's used automatically — no restart needed.";
+let voiceChoice;
+/** Forget the choice, so a voice downloaded meanwhile is picked up (voice_setup calls this). */
+export function resetVoiceChoice() {
+    voiceChoice = undefined;
+}
+export function chooseVoice() {
+    voiceChoice ??= (async () => {
+        if (CONFIG.voice) {
+            return CONFIG.voice.toLowerCase() === "default"
+                ? { label: "the system voice (VOICE_MCP_VOICE=default)", canUpgrade: false }
+                : { voice: CONFIG.voice, label: `${CONFIG.voice} (set by VOICE_MCP_VOICE)`, canUpgrade: false };
+        }
+        const bin = IS_MAC ? findTts() : null;
+        if (!bin)
+            return { label: "the system voice", canUpgrade: false };
+        try {
+            const r = await run(bin, ["-v", "?"], { timeoutMs: 10_000 });
+            const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+            const best = pickVoice(parseSayVoices(r.stdout), CONFIG.language, locale);
+            if (best)
+                return { voice: best.name, label: `${best.name} — the most natural voice installed`, canUpgrade: false };
+        }
+        catch {
+            /* fall back to the system voice */
+        }
+        return { label: "the system voice", canUpgrade: true };
+    })();
+    return voiceChoice;
+}
 export async function speak(text, signal) {
     if (!text)
         return;
@@ -24,8 +80,9 @@ export async function speak(text, signal) {
     let result;
     if (IS_MAC) {
         const args = [];
-        if (CONFIG.voice)
-            args.push("-v", CONFIG.voice);
+        const { voice } = await chooseVoice();
+        if (voice)
+            args.push("-v", voice);
         if (CONFIG.rate)
             args.push("-r", CONFIG.rate);
         args.push("-f", "-"); // read from stdin: no argv length limits, no flag injection

package/dist/config.js

@@ -32,7 +32,10 @@ const CACHE_ROOT = process.env.VOICE_MCP_CACHE_DIR?.trim() ||
     path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "mac-voice-mcp");
 export const CONFIG = {
     // --- Speaking
-    /** macOS voice name, e.g. "Samantha" (`say -v '?'` lists them). */
+    /**
+     * macOS voice name, e.g. "Ava (Premium)" (`say -v '?'` lists them). Unset: the most natural
+     * installed voice for the language (Premium, then Enhanced), else the system voice. "default": always the system voice.
+     */
     voice: process.env.VOICE_MCP_VOICE?.trim() || undefined,
     /** Speech rate in words per minute (macOS `say -r`). */
     rate: process.env.VOICE_MCP_RATE?.trim() || undefined,

package/dist/setup.js

@@ -7,7 +7,7 @@
  * the result. A slow `brew install` can never time the client out.
  */
 import { statSync } from "node:fs";
-import { describeRecorder, findRecorder, findTts } from "./audio.js";
+import { chooseVoice, describeRecorder, findRecorder, findTts, resetVoiceChoice, VOICE_UPGRADE_HINT } from "./audio.js";
 import { CONFIG, IS_MAC, IS_WIN, log } from "./config.js";
 import { ensureModel, isModelDownloading, locateModel, modelSource, MODEL_SIZES_MB } from "./model.js";
 import { isExecutable, resetWhichCache, run, sleep, tail, which } from "./proc.js";
@@ -68,6 +68,13 @@ async function checkRequirements() {
     checks.push(tts
         ? { label: "Text-to-speech", status: "ok", detail: IS_MAC ? "macOS `say` (built in)" : tts }
         : { label: "Text-to-speech", status: "missing", detail: "no engine found — install espeak-ng (`sudo apt install espeak-ng`)" });
+    if (tts && IS_MAC) {
+        resetVoiceChoice(); // pick up a voice downloaded since the last check
+        const choice = await chooseVoice();
+        checks.push(choice.canUpgrade
+            ? { label: "Voice", status: "optional", detail: `${choice.label} — ${VOICE_UPGRADE_HINT}` }
+            : { label: "Voice", status: "ok", detail: choice.label });
+    }
     const rec = findRecorder();
     checks.push(rec
         ? { label: "Recorder", status: "ok", detail: describeRecorder(rec) }
@@ -162,6 +169,9 @@ export async function runSetupFlow(install, onProgress) {
     lines.push("");
     if (ready) {
         lines.push("Next: everything is in place — speak_and_listen is ready to use.");
+        if (checks.some((c) => c.label === "Voice" && c.status === "optional")) {
+            lines.push("Mention the optional voice tip (•) to the user once — it makes the voice sound far more natural. Nothing else to do.");
+        }
     }
     else if (installing) {
         lines.push("Next: installation is still running in the background. Tell the user, wait about a minute, then call voice_setup again (install=false) to check.");

package/dist/speech-text.js

@@ -3,6 +3,18 @@
  *   - prepareSpeech: turn "screen text" into "ear text" before it's spoken
  *   - cleanTranscript: strip whisper.cpp's non-speech markers from a transcript
  */
+/**
+ * Phrases that send the user to look at something. Deliberately specific: bare words like
+ * "above", "below" or "see the" also occur in ordinary speech ("above thirty degrees",
+ * "see the doctor") and must not trigger the reminder.
+ */
+const ON_SCREEN_PATTERN = new RegExp([
+    String.raw `\bon[\s-]?screen\b`,
+    String.raw `\bI(?:['’]ve| have)\s+(?:printed|pasted|put|posted|listed|written|shown|added)\b`,
+    String.raw `\b(?:printed|pasted|posted|listed|shown|written)\s+(?:it\s+|them\s+)?(?:below|above|here)\b`,
+    String.raw `\b(?:see|check|look at|scroll to)\s+(?:the\s+)?(?:screen|chat|reply|message|details|output|table|diff|log)\b`,
+    String.raw `\bin (?:the|my) (?:reply|message|chat)\b`,
+].join("|"), "i");
 /**
  * Safety net for speakability. The model is asked (tool description, server
  * instructions, voice_mode prompt) to send plain spoken sentences; this catches
@@ -89,6 +101,14 @@ export function prepareSpeech(input, opts = {}) {
                 "Next time send only short, plain spoken sentences — keep code, paths, links and tables in your on-screen reply.",
         ]
         : [];
+    // When the spoken text points the user at something to look at, remind the model that only
+    // its own assistant message renders — not the speech, and not Bash/tool output (issue #3).
+    // Checked on the original input, so the "The rest is on screen." added above doesn't count.
+    if (ON_SCREEN_PATTERN.test(input)) {
+        noteList.push("voice-mcp reminder: you told the user to look at something. Spoken text and Bash/tool output are " +
+            "NOT visible to them — only your own assistant message is. Make sure those details are written in " +
+            "your reply for this turn.");
+    }
     return { text: s, notes: noteList };
 }
 /** Remove timestamps and non-speech markers like [BLANK_AUDIO] from whisper output. */

package/dist/stt.js

@@ -71,7 +71,7 @@ function freePort() {
         });
     });
 }
-/** fetch() with a timeout that also honours the caller's abort signal (Node 18 compatible). */
+/** fetch() with a timeout that also honours the caller's abort signal (works without AbortSignal.any). */
 async function fetchWithin(url, init, timeoutMs, signal) {
     const ctl = new AbortController();
     const timer = setTimeout(() => ctl.abort(), timeoutMs);

package/dist/texts.js

@@ -12,6 +12,8 @@ export const SPEECH_RULES = [
     '  not paths ("in index.ts"), round numbers ("about two hundred ms"), spell out symbols.',
     '- Ask one question at a time, answerable in a few words ("Should I deploy it — yes or no?").',
     "- Put the details (diffs, logs, links) in your normal on-screen reply, and say so out loud.",
+    "- Tool output (Bash stdout, file writes) is NOT the on-screen reply. Only your own assistant message text renders.",
+    "- A spoken turn with no assistant message text shows the user nothing — never skip the on-screen reply.",
 ].join("\n");
 /** Claude Code reads these (truncated at 2 KB) — keep under that. */
 export const SERVER_INSTRUCTIONS = [
@@ -48,6 +50,7 @@ export const SPEAK_TOOL_DESCRIPTION = [
     "Once the user is talking with you by voice, keep the conversation in voice: answer each transcript with",
     "another speak_and_listen call (not a text reply) until they say stop or start typing.",
     'A reply of "(No speech detected …)" means the user did not answer — never treat it as consent.',
+    'The "voice-mcp timing" line at the end is diagnostics: ignore it unless the user asks why things feel slow.',
     "If it reports that voice-mcp is not set up, call voice_setup.",
 ].join("\n");
 export const SETUP_TOOL_DESCRIPTION = [

package/dist/voice.js

@@ -29,12 +29,15 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
         const t0 = Date.now();
         onPhase?.("speaking");
         await speak(speech.text, signal);
+        const spoke = Date.now() - t0;
         await chime("start");
         onPhase?.("listening");
+        const tListen = Date.now();
         const heard = await listenForTurn(seconds, wav, signal);
         void chime("stop");
         const t1 = Date.now();
         debug("listen:", heard);
+        const timing = (transcribedMs) => timingNote({ spokeMs: spoke, listenedMs: t1 - tListen, talkedSeconds: heard.speechSeconds, transcribedMs });
         if (heard.digitalSilence) {
             return {
                 ok: false,
@@ -45,12 +48,12 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
         const waited = Math.min(CONFIG.startTimeoutSeconds, seconds);
         const noSpeech = `(No speech detected — the user did not reply within ${waited} seconds.)`;
         if (heard.reason === "no-speech")
-            return { ok: true, text: noSpeech, notes };
+            return { ok: true, text: noSpeech, notes: [...notes, timing()] };
         onPhase?.("transcribing");
         const transcript = await transcribe(wav, model, signal);
-        debug(`timing: speak+listen ${t1 - t0} ms, transcribe ${Date.now() - t1} ms`);
+        const transcribed = Date.now() - t1;
         if (!transcript)
-            return { ok: true, text: noSpeech, notes };
+            return { ok: true, text: noSpeech, notes: [...notes, timing(transcribed)] };
         if (heard.reason === "max-duration") {
             const l = heard.levels;
             const f = (n) => (Number.isFinite(n) ? n.toFixed(0) : "?");
@@ -59,12 +62,23 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
                 `(Audio levels, for tuning: background ${f(l.floorDb)} dB, voice ${f(l.speechDb)} dB, ` +
                 `last second ${f(l.recentDb)} ± ${l.recentSpreadDb.toFixed(1)} dB.)`);
         }
-        return { ok: true, text: transcript, notes };
+        return { ok: true, text: transcript, notes: [...notes, timing(transcribed)] };
     }
     finally {
         await rm(tmpDir, { recursive: true, force: true });
     }
 }
+const secs = (ms) => `${(ms / 1000).toFixed(1)} s`;
+/** One compact line per turn, so "why did that feel slow?" has an answer. */
+export function timingNote(t) {
+    const parts = [
+        `spoke ${secs(t.spokeMs)}`,
+        `listened ${secs(t.listenedMs)}` + (t.talkedSeconds > 0 ? ` (user talked ${t.talkedSeconds.toFixed(1)} s)` : " (no speech)"),
+    ];
+    if (t.transcribedMs !== undefined)
+        parts.push(`transcribed ${secs(t.transcribedMs)}`);
+    return `voice-mcp timing: ${parts.join(" · ")}`;
+}
 /** Serialize calls: there is one speaker and one microphone. */
 let queue = Promise.resolve();
 export function exclusive(fn) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mac-voice-mcp",
   "mcpName": "io.github.jeet0007/mac-voice-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Talk with Claude out loud on your Mac: speaks with macOS `say`, listens for one natural conversational turn, and transcribes on-device with whisper.cpp. An MCP server.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "dist",
     "examples",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
@@ -25,7 +26,9 @@
     "inspect": "npx -y @modelcontextprotocol/inspector node dist/index.js",
     "prepare": "npm run build",
     "prepublishOnly": "npm test",
-    "audit": "npm audit --omit=dev --audit-level=high && npm audit signatures"
+    "audit": "npm audit --omit=dev --audit-level=high && npm audit signatures",
+    "preversion": "npm test",
+    "version": "node scripts/sync-version.mjs && git add server.json .claude-plugin/plugin.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
@@ -36,7 +39,7 @@
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=18.17"
+    "node": ">=22"
   },
   "keywords": [
     "mcp",