mac-voice-mcp 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,18 +1,75 @@
 # Changelog
 
-## 0.1.1
+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.3.0] - 2026-09-28
+
+### Added
+- **Voice conversations stay in voice (Claude Code plugin).** Once you've answered out loud, a plugin hook sends Claude back to reply by voice if it tries to answer in text. It does this at most once per spoken answer, so it can never loop. Voice mode ends when you type, when you don't answer, or when Claude says goodbye with `listen: false`. It's tracked per session and expires after 30 idle minutes. `VOICE_MCP_STAY_IN_VOICE=0` turns the hook off.
+- **`speak_and_listen` with `listen: false`** speaks without opening the microphone, for one-way announcements or a goodbye. It needs only text-to-speech, not the recorder, whisper or a model.
+- **One voice turn at a time across the whole Mac.** Claude Code windows, Claude Desktop and Cursor take turns at the speaker and mic, one turn at a time, so they never talk over each other. A waiting turn reports "waiting for another voice session" and gives up after `VOICE_MCP_LOCK_WAIT_SECONDS` (120) with a clear message. A lock left by a crashed session is taken over. If the cache folder isn't writable, turns go ahead without the lock.
+- **README: an Upgrading section and a Voice mode section, plus a note on testing the plugin from a checkout.**
+
+### Changed
+- **Claude waits longer for you to start talking: 15 seconds, up from 8** (`VOICE_MCP_START_TIMEOUT_SECONDS`), so reading or thinking doesn't end the conversation.
+- **When you don't answer, Claude asks once more, then pauses cleanly.** The "no speech" result now tells Claude that the mic is off, so it tells you to type to carry on rather than to speak.
+
+### Removed
+- The unused `packaging/` folder. `.github/` is the only copy of the workflows.
+
+## [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 gets a reminder 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 then narrowed so that ordinary sentences like "above thirty degrees" or "see the doctor" don't set it off.
+- **"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.
 
-### Docs and tooling
-- README: one-click install buttons for Cursor and VS Code, and install steps for the Claude Code plugin marketplace and the official MCP Registry.
-- Security: TruffleHog secret scanning, CodeQL, dependency review, `npm audit` in CI, and Dependabot.
-- Releases publish through npm trusted publishing, with provenance.
+## [0.1.0] - 2026-09-23
 
-## 0.1.0
+### 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.
 
-First release: `speak_and_listen` (natural turn-taking, on-device whisper.cpp with a warm server), `voice_setup` (check first, install only what's missing, only after you agree), and 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

@@ -51,7 +51,7 @@ The server has **two tools and two prompts**:
 | `/mcp__voice-mcp__setup` | A guided setup: it checks, asks you, installs, then runs a spoken test. |
 | `/mcp__voice-mcp__voice_mode` | A hands-free session where Claude checks in by voice at natural points. |
 
-**Listening works like a conversation.** A soft chime plays when the mic opens. The server waits for you to start talking and hands back to Claude about a second after you stop. It adjusts to background noise, doesn't cut you off at pauses mid-sentence, and ignores coughs and clicks. If you say nothing for 8 seconds, Claude gets "no speech", which it is told never to treat as a yes.
+**Listening works like a conversation.** A soft chime plays when the mic opens. The server waits for you to start talking and hands back to Claude about a second after you stop. It adjusts to background noise, doesn't cut you off at pauses mid-sentence, and ignores coughs and clicks. If you say nothing for 15 seconds, Claude gets "no speech", which it is told never to treat as a yes.
 
 **Replies come back fast.** whisper.cpp's server keeps the speech model loaded between turns, and the model starts loading while Claude is still talking. You don't wait for a model load on each reply. After 15 idle minutes the server shuts down to free memory. It is stopped automatically even if the MCP server crashes.
 
@@ -64,9 +64,9 @@ You need **Node.js 22 or newer**. Whichever way you install, run setup once afte
 ### One click
 
 <p>
-  <a href="https://cursor.com/en/install-mcp?name=voice-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1hYy12b2ljZS1tY3AiXX0%3D"><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%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%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>
+  <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>
 
 ### From a marketplace
@@ -76,6 +76,7 @@ You need **Node.js 22 or newer**. Whichever way you install, run setup once afte
   /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`, a skill that teaches Claude how to use voice well and fix common problems, and a hook that keeps a voice conversation in voice (see [Voice mode](#voice-mode)). 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
@@ -83,7 +84,7 @@ You need **Node.js 22 or newer**. Whichever way you install, run setup once afte
 **Claude Code**
 
 ```bash
-claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp
+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:
@@ -93,12 +94,14 @@ claude mcp add voice-mcp -s user -- npx -y mac-voice-mcp
   "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`.
@@ -106,20 +109,20 @@ If you get `spawn npx ENOENT`, use the full path from `which npx`, e.g. `"comman
 **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"]}'
+code --add-mcp '{"name":"voice-mcp","command":"npx","args":["-y","mac-voice-mcp@latest"]}'
 ```
 
-**Any other MCP client.** Run `npx -y mac-voice-mcp` as a stdio server.
+**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 `/mcp__voice-mcp__setup`, or from a terminal run `npx -y mac-voice-mcp setup`.
+**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/` |
@@ -130,6 +133,25 @@ Setup checks what's already there before it changes anything:
 
 **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
 
 One command does everything above: it builds the project, runs setup (asking before installing anything), adds voice-mcp to Claude Desktop (backing up your config first) and to Claude Code, and offers a spoken test. It's safe to re-run, because each step checks first and skips anything already done.
@@ -138,13 +160,33 @@ One command does everything above: it builds the project, runs setup (asking bef
 git clone https://github.com/jeet0007/mac-voice-mcp && bash mac-voice-mcp/install.sh
 ```
 
+## Upgrading
+
+- **Claude Code plugin:** run `/plugin marketplace update mac-voice-mcp`, then open `/plugin`, choose mac-voice-mcp under your installed plugins, and update it. Restart Claude Code. If there's no update option, uninstall and reinstall it.
+- **Everything installed with `mac-voice-mcp@latest`** (Claude Desktop, Cursor, VS Code, `claude mcp add`): restart the app. npx fetches the new release when the server starts.
+- **Configs without `@latest`:** change `mac-voice-mcp` to `mac-voice-mcp@latest` in the config, then restart the app. Otherwise npx keeps running the version it cached first.
+
+Check which version you'd get with `npx -y mac-voice-mcp@latest --version`, and see what changed in the [changelog](CHANGELOG.md). Your model, voice and settings carry over.
+
 ## 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.
 
+### Voice mode
+
+Once you answer out loud, you're in a voice conversation. Claude replies by voice, not in text, until one of these happens:
+
+- **You type something.** You're back at the keyboard.
+- **You say you're done.** Claude says a short goodbye without opening the mic (`speak_and_listen` with `listen: false`).
+- **You don't answer.** After 15 seconds of silence Claude asks once more. If you still don't answer, it pauses and summarizes on screen, and the mic stays off. Type anything, or run `/mac-voice-mcp:talk`, to pick up again.
+
+In Claude Code, the plugin enforces this with a hook. If Claude tries to answer in text mid-conversation, the hook sends it back once to answer by voice. If it stops again, the hook lets it. To turn the hook off, add `"VOICE_MCP_STAY_IN_VOICE": "0"` to the `env` block in `~/.claude/settings.json`. Other apps rely on the instructions alone.
+
+**Several sessions, one mic.** Every mac-voice-mcp on your Mac takes turns: Claude Code windows, Claude Desktop and Cursor. While one is speaking or listening, the others wait for that turn to finish (shown as "waiting for another voice session"). They give up after 2 minutes with a message. If a session crashes, the next one takes the mic over.
+
 ## Getting Claude to sound natural
 
 Guidance reaches Claude through several channels, because each client shows different ones:
@@ -155,6 +197,7 @@ Guidance reaches Claude through several channels, because each client shows diff
 | Server instructions (when to use voice, how to handle replies, setup) | Claude Code (it reads up to 2 KB) |
 | The `voice_mode` and `setup` prompts | Claude Code (as slash commands), Claude Desktop, Cursor |
 | Server-side rewrite plus a `voice-mcp note` back to Claude | Always on |
+| The plugin's `/mac-voice-mcp:talk`, `voice-help` skill and stay-in-voice hook | Claude Code, with the plugin |
 
 The rules Claude is given:
 
@@ -178,17 +221,18 @@ 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. |
+| `VOICE_MCP_LOCK_WAIT_SECONDS` | `120` | How long a turn waits while another session on this Mac is using the mic. |
 
 **Listening**
 
 | Variable | Default | |
 |---|---|---|
 | `VOICE_MCP_END_SILENCE_MS` | `1200` | How long a pause ends your turn. Use `1800` if it cuts you off while you think, `800` for snappier replies. |
-| `VOICE_MCP_START_TIMEOUT_SECONDS` | `8` | How long to wait for you to start talking. |
+| `VOICE_MCP_START_TIMEOUT_SECONDS` | `15` | How long to wait for you to start talking. |
 | `VOICE_MCP_SPEECH_MARGIN_DB` | `12` | How much louder than room noise counts as speech. Raise it in noisy rooms. |
 | `VOICE_MCP_MIN_SPEECH_DB` | `-48` | The quietest level that ever counts as speech (dBFS). |
 | `VOICE_MCP_RECORDER` | `auto` | `sox` or `ffmpeg` (`ffmpeg` is macOS only). |
@@ -208,6 +252,12 @@ Everything is optional. Set these in your client config's `"env": { … }` block
 | `VOICE_MCP_CACHE_DIR` | `~/.cache/mac-voice-mcp` | Where models are downloaded or symlinked. |
 | `VOICE_MCP_DEBUG` | `0` | Verbose logs with per-turn timings, written to stderr. |
 
+**Claude Code plugin hook.** Set this in the `env` block of `~/.claude/settings.json`, not in the server's config:
+
+| Variable | Default | |
+|---|---|---|
+| `VOICE_MCP_STAY_IN_VOICE` | `1` | Set to `0` to stop the plugin's hook from sending Claude back to answer by voice. |
+
 **Models** (whisper.cpp names):
 
 | Model | Size | Good for |
@@ -221,7 +271,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`). |
@@ -229,13 +279,18 @@ 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). |
+| "Another voice session on this Mac…" | Another Claude window, Claude Desktop or Cursor held the speaker and mic for over 2 minutes, which means one very long turn. End that conversation, then try again. |
+| Claude keeps answering by voice after I'm done | Type anything, or say "stop voice mode". To switch the plugin's hook off entirely, see [Voice mode](#voice-mode). |
+| 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
 
 - **You can't interrupt it.** It finishes speaking, then listens. Barge-in would mean listening while the speakers play, which needs headphones or echo cancellation.
 - **It's macOS-first.** Linux works with SoX and espeak-ng. Windows is untested.
 - **Turn-taking is based on loudness, not a speech model.** It adapts to background noise, but very noisy rooms, music or TV can confuse it. A headset helps, and so do the listening settings above.
-- **One conversation at a time.** There's one speaker and one microphone, so calls are queued.
+- **One conversation at a time.** There's one speaker and one microphone, so turns from every session on the Mac are queued.
 
 ## Privacy and safety
 
@@ -256,7 +311,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
@@ -272,14 +327,23 @@ npm run inspect        # MCP Inspector
 | `model.ts` | Finding, symlinking or downloading the model |
 | `stt.ts` | The warm `whisper-server` with orphan guard, and the `whisper-cli` fallback |
 | `setup.ts` | Requirement checks and consent-based background installs |
+| `lock.ts` | One voice turn at a time across every session on the Mac |
 | `voice.ts`, `server.ts`, `index.ts` | The round trip, the MCP tools and prompts, and the CLI |
+| `skills/`, `hooks/` | The Claude Code plugin's `/mac-voice-mcp:talk` and `:setup` commands, the `voice-help` skill, and the stay-in-voice hook |
 
 The package installs two commands: `mac-voice-mcp` (the one `npx -y mac-voice-mcp` runs), and `voice-mcp`.
 
+**Testing the plugin: don't start Claude Code inside this repo.** In this folder, `npx mac-voice-mcp@<this version>` finds the checkout itself instead of downloading the package, can't run it, and the server fails with `CONNECTION_CLOSED`. Start `claude` in any other folder. To try unreleased plugin files (skills, hooks), swap the marketplace to your checkout: run `/plugin marketplace remove mac-voice-mcp`, then `/plugin marketplace add /path/to/checkout`, and install at user scope. The server still comes from npm, so test server changes with `npm test` and `npm run test:voice`.
+
 ### 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

@@ -31,8 +31,15 @@ const modelName = (process.env.VOICE_MCP_WHISPER_MODEL ?? "base.en").trim();
 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 = {
+    /** Models, the mic lock and hook state live here. */
+    cacheDir: CACHE_ROOT,
+    /** How long a voice turn waits for another session to finish with the mic. */
+    lockWaitSeconds: Math.max(1, envNum("VOICE_MCP_LOCK_WAIT_SECONDS", 120)),
     // --- 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,
@@ -44,7 +51,7 @@ export const CONFIG = {
     /** End of turn: stop listening after this much silence once the user has spoken. */
     endSilenceMs: Math.max(300, envNum("VOICE_MCP_END_SILENCE_MS", 1200)),
     /** Give up if the user hasn't started talking within this many seconds. */
-    startTimeoutSeconds: Math.max(1, envNum("VOICE_MCP_START_TIMEOUT_SECONDS", 8)),
+    startTimeoutSeconds: Math.max(1, envNum("VOICE_MCP_START_TIMEOUT_SECONDS", 15)),
     /** Speech must be this many dB above the room's background noise. Lower = more sensitive. */
     speechMarginDb: envNum("VOICE_MCP_SPEECH_MARGIN_DB", 12),
     /** …and never quieter than this absolute level (dBFS). */

package/dist/index.js

@@ -84,7 +84,10 @@ async function runSetupCli(args) {
 async function runTestCli(text) {
     const prompt = text || "Voice bridge test. Say something after the chime, and I'll print what I heard.";
     try {
-        const result = await speakAndListen(prompt, envNum("VOICE_MCP_TEST_SECONDS", DEFAULT_LISTEN_SECONDS), undefined, (p) => console.error(`  … ${p}`));
+        const result = await speakAndListen(prompt, {
+            listenSeconds: envNum("VOICE_MCP_TEST_SECONDS", DEFAULT_LISTEN_SECONDS),
+            onPhase: (p) => console.error(`  … ${p}`),
+        });
         process.stdout.write(result.text + "\n");
         for (const note of result.notes)
             console.error(note);

package/dist/lock.js

@@ -0,0 +1,162 @@
+/**
+ * One voice turn at a time across every voice-mcp on this Mac — several Claude Code windows,
+ * Claude Desktop and Cursor all share one speaker and one microphone.
+ *
+ * The lock is a file created atomically (O_EXCL) holding the owner's pid and start time.
+ * A lock whose owner has died (or that is implausibly old) is taken over, so a crash never
+ * blocks the mic for good. If the lock can't be used at all (read-only or missing cache
+ * folder), turns go ahead without it rather than failing.
+ */
+import { closeSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import path from "node:path";
+import { CONFIG, debug } from "./config.js";
+import { CancelledError, sleep } from "./proc.js";
+/** Longer than any real turn (speaking, up to two minutes of listening, transcribing). */
+const STALE_AFTER_MS = 10 * 60_000;
+/** A lock file that's still unreadable after this long was never going to be written. */
+const UNREADABLE_GRACE_MS = 5_000;
+const POLL_MS = 250;
+export class MicBusyError extends Error {
+    name = "MicBusyError";
+}
+export const lockFile = () => path.join(CONFIG.cacheDir, "mic.lock");
+function readOwner(file) {
+    try {
+        const o = JSON.parse(readFileSync(file, "utf8"));
+        return Number.isInteger(o.pid) && Number.isFinite(o.since) ? o : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM"; // exists, owned by someone else
+    }
+}
+/** The lock file's identity (inode) if it's stale, otherwise null. */
+function staleIdentity(file, now) {
+    let ino;
+    let mtimeMs;
+    try {
+        ({ ino, mtimeMs } = statSync(file));
+    }
+    catch {
+        return null; // gone already; the next attempt will create it
+    }
+    const owner = readOwner(file);
+    const stale = owner ? !isAlive(owner.pid) || now - owner.since > STALE_AFTER_MS : now - mtimeMs > UNREADABLE_GRACE_MS;
+    return stale ? ino : null;
+}
+/**
+ * Remove a stale lock without ever removing a fresh one someone else just created: move it aside
+ * atomically, check it's the same file we judged stale, and put it back if it isn't.
+ */
+function takeOver(file, ino) {
+    const aside = `${file}.${process.pid}.${Date.now()}.stale`;
+    try {
+        renameSync(file, aside);
+    }
+    catch {
+        return; // another session got there first
+    }
+    try {
+        if (statSync(aside).ino !== ino) {
+            try {
+                linkSync(aside, file); // it was a live lock after all: restore it (fails harmlessly if one exists)
+            }
+            catch {
+                /* a newer lock is already in place */
+            }
+        }
+    }
+    finally {
+        try {
+            unlinkSync(aside);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Remove the file only if it's still ours. */
+function releaseIfOurs(file, me) {
+    const now = readOwner(file);
+    if (!now || now.pid !== me.pid || now.since !== me.since)
+        return;
+    try {
+        unlinkSync(file);
+    }
+    catch {
+        /* already gone */
+    }
+}
+const UNUSABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT", "ENOTDIR"]);
+const noLock = () => { };
+/** Wait for the mic, take it, and return the function that gives it back. */
+export async function acquireMicLock(opts = {}) {
+    const file = lockFile();
+    const waitMs = opts.waitMs ?? CONFIG.lockWaitSeconds * 1000;
+    const deadline = Date.now() + waitMs;
+    let waiting = false;
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+    }
+    catch (e) {
+        debug("mic lock unavailable, continuing without it:", e.message);
+        return noLock;
+    }
+    for (;;) {
+        if (opts.signal?.aborted)
+            throw new CancelledError();
+        const me = { pid: process.pid, since: Date.now() };
+        try {
+            const fd = openSync(file, "wx");
+            try {
+                writeSync(fd, JSON.stringify(me));
+            }
+            finally {
+                closeSync(fd);
+            }
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                process.off("exit", release);
+                releaseIfOurs(file, me);
+            };
+            process.on("exit", release); // a normal shutdown mid-turn still frees the mic
+            return release;
+        }
+        catch (e) {
+            const code = e.code ?? "";
+            if (UNUSABLE.has(code)) {
+                debug("mic lock unavailable, continuing without it:", e.message);
+                return noLock;
+            }
+            if (code !== "EEXIST")
+                throw e;
+        }
+        const ino = staleIdentity(file, Date.now());
+        if (ino !== null) {
+            debug("taking over a stale mic lock");
+            takeOver(file, ino);
+            continue;
+        }
+        if (!waiting) {
+            waiting = true;
+            opts.onWait?.();
+        }
+        if (Date.now() > deadline) {
+            throw new MicBusyError("Another voice session on this Mac (another Claude window, Claude Desktop or Cursor) has been using the " +
+                `speaker and microphone for over ${Math.round(waitMs / 1000)} seconds. ` +
+                "Tell the user on screen, and try again once its current turn is over.");
+        }
+        await sleep(POLL_MS);
+    }
+}

package/dist/server.js

@@ -37,12 +37,23 @@ export function createServer() {
                 .optional()
                 .describe(`Upper limit on how long to listen, in seconds (default ${DEFAULT_LISTEN_SECONDS}, max ${MAX_LISTEN_SECONDS}). ` +
                 "Listening already stops when the user finishes talking, so you rarely need this."),
+            listen: z
+                .boolean()
+                .optional()
+                .describe("Default true. false: only speak, without opening the microphone — for a one-way announcement, " +
+                "or to say goodbye when the user ends voice mode."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, async ({ text_to_speak, listen_seconds }, extra) => {
+    }, async ({ text_to_speak, listen_seconds, listen }, extra) => {
         const progress = progressReporter(extra);
+        const phaseMessage = (phase) => phase === "waiting" ? "waiting for another voice session on this Mac to finish" : phase;
         try {
-            const result = await exclusive(() => speakAndListen(text_to_speak, listen_seconds ?? DEFAULT_LISTEN_SECONDS, extra.signal, (phase) => progress?.(phase)));
+            const result = await exclusive(() => speakAndListen(text_to_speak, {
+                listenSeconds: listen_seconds ?? DEFAULT_LISTEN_SECONDS,
+                listen,
+                signal: extra.signal,
+                onPhase: (phase) => progress?.(phaseMessage(phase)),
+            }));
             return {
                 content: [{ type: "text", text: result.text }, ...result.notes.map((note) => ({ type: "text", text: `\n\n${note}` }))],
                 isError: !result.ok,

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/texts.js

@@ -30,8 +30,8 @@ export const SERVER_INSTRUCTIONS = [
     '- "(No speech detected …)" means no answer: never treat silence as consent. Ask once more or',
     "  continue with safe work and report on screen.",
     "- Once the user is talking with you by voice, stay in voice: answer every turn with speak_and_listen,",
-    "  not a text reply, until they say stop or start typing.",
-    "- Listening ends on its own when the user stops talking; no need to set listen_seconds.",
+    "  not a text reply, until they say stop (say goodbye with listen: false) or start typing.",
+    "- Listening ends when the user stops talking; listen_seconds is rarely needed.",
     '- If the result includes a "voice-mcp note", follow it.',
     "",
     "Setup: if speak_and_listen says voice-mcp is not set up, call voice_setup (check only), tell the user",
@@ -49,7 +49,10 @@ 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.',
+    "To end voice mode, or for a one-way announcement, pass listen: false: it speaks without opening the mic.",
+    'A reply of "(No speech detected …)" means the user did not answer — never treat it as consent. Ask once more;',
+    "if still nothing, stop and say on screen that voice mode is paused and they can type to carry on (not speak: the mic is off).",
+    '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 = [
@@ -80,9 +83,11 @@ export const VOICE_MODE_PROMPT = (task) => [
     "  Don't narrate every small action.",
     "- If a transcript is unclear, ask again by voice.",
     "- Confirm by voice before anything destructive, irreversible, or that costs money.",
-    "- If I don't answer, don't assume yes: carry on with safe work or pause, and summarize on screen.",
+    "- If I don't answer, don't assume yes: ask once more out loud. If there's still nothing, pause and summarize",
+    "  on screen, and tell me to type anything to pick up again (the mic is off, so don't tell me to speak).",
     "- Keep writing full details (code, diffs, links) on screen as usual; the voice line is the headline.",
-    '- Stop using voice when I say "stop voice mode", "I\'m back", or start typing again.',
+    '- Stop using voice when I say "stop voice mode", "I\'m back", or start typing again. To end it, say a short',
+    "  goodbye with speak_and_listen and listen: false (it speaks without opening the mic).",
     "",
     SPEECH_RULES,
     "",

package/dist/voice.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { chime, findRecorder, listenForTurn, MIC_PERMISSION_HINT, RECORDER_MISSING, speak } from "./audio.js";
 import { CONFIG, debug, DEFAULT_LISTEN_SECONDS, MAX_LISTEN_SECONDS, MAX_SPEAK_CHARS } from "./config.js";
+import { acquireMicLock, MicBusyError } from "./lock.js";
 import { ensureModel } from "./model.js";
 import { SetupError } from "./proc.js";
 import { prepareSpeech } from "./speech-text.js";
@@ -16,11 +17,33 @@ async function preflight() {
         throw new SetupError(STT_MISSING);
     return { model: await ensureModel({ download: false }) };
 }
-export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase) {
-    const seconds = Math.min(MAX_LISTEN_SECONDS, Math.max(1, Number.isFinite(listenSeconds) ? listenSeconds : DEFAULT_LISTEN_SECONDS));
-    const { model } = await preflight();
-    // Load the model into the warm server while we talk, so it's ready when the user finishes.
-    prewarm(model);
+export async function speakAndListen(textToSpeak, opts = {}) {
+    const { signal, onPhase } = opts;
+    const listen = opts.listen !== false;
+    const requested = opts.listenSeconds ?? DEFAULT_LISTEN_SECONDS;
+    const seconds = Math.min(MAX_LISTEN_SECONDS, Math.max(1, Number.isFinite(requested) ? requested : DEFAULT_LISTEN_SECONDS));
+    const model = listen ? (await preflight()).model : null;
+    // Load the model into the warm server now, so it's ready when the user finishes (even if we wait below).
+    if (model)
+        prewarm(model);
+    // Wait for any other voice session on this Mac to finish with the speaker and mic.
+    let release;
+    try {
+        release = await acquireMicLock({ signal, onWait: () => onPhase?.("waiting") });
+    }
+    catch (err) {
+        if (err instanceof MicBusyError)
+            return { ok: false, text: err.message, notes: [] };
+        throw err;
+    }
+    try {
+        return await turn(textToSpeak, seconds, model, signal, onPhase);
+    }
+    finally {
+        release();
+    }
+}
+async function turn(textToSpeak, seconds, model, signal, onPhase) {
     const speech = prepareSpeech(textToSpeak, { maxWords: CONFIG.maxSpeakWords, maxChars: MAX_SPEAK_CHARS });
     const notes = [...speech.notes];
     const tmpDir = await mkdtemp(path.join(os.tmpdir(), "voice-mcp-"));
@@ -29,12 +52,19 @@ export async function speakAndListen(textToSpeak, listenSeconds, signal, onPhase
         const t0 = Date.now();
         onPhase?.("speaking");
         await speak(speech.text, signal);
+        const spoke = Date.now() - t0;
+        if (!model) {
+            const text = "(Spoken. The microphone was not opened, because listen was false.)";
+            return { ok: true, text, notes: [...notes, `voice-mcp timing: spoke ${secs(spoke)}`] };
+        }
         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,
@@ -43,14 +73,16 @@ 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.)`;
+        const noSpeech = `(No speech detected — the user did not reply within ${waited} seconds. The microphone is now off. ` +
+            "Ask once more out loud. If there's still no answer, stop and say on screen that voice mode is paused " +
+            "and they can type anything to carry on — speaking won't work until you call speak_and_listen again.)";
         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 +91,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.1",
+  "version": "0.3.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": {
@@ -26,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",