vibeaudio 0.19.0 → 0.20.0

package/README.md

@@ -147,7 +147,7 @@ Want the music to follow what the agent is doing — calm while it reads, busies
 vibe --reactive --install-hooks
 ```
 
-Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you. Installing hooks doesn't start the agent: open it whenever you like, and the music plays from your first prompt. ("Just launch it" and "This session only" do start it.)
+Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you. The menu's last entry, **Alerts & extras**, flips the saved toggles (banners, spoken announcements, `vibe --announce`, music, a one-hour mute) without a flag to remember. Installing hooks doesn't start the agent: open it whenever you like, and the music plays from your first prompt. ("Just launch it" and "This session only" do start it.)
 
 Now run your agent normally, with no prefix. Music starts when you submit a prompt and stops with a chime when the agent finishes. [Details below.](#-agent-hooks-no-wrapper-needed)
 
@@ -314,7 +314,8 @@ Every session of an agent is tracked separately, by the session id in its hook p
 * **The music plays while any session is working.** A second prompt doesn't restart it, and it stops only when the last working session finishes.
 * **Every session gets its own chime.** A quick question that finishes while another agent is still busy chimes "done" and the music carries on underneath.
 
-* **Which one?** With three terminals going, a chime says something finished and leaves you alt-tabbing to find out what. `vibe --notify` adds a desktop banner — `api: finished`, `web: needs you (Bash)` — named after the project the session runs in. Off by default, since a banner is more intrusive than a sound; macOS (`osascript`) and Linux (`notify-send`, needs a notification daemon), nothing on Windows yet. A mute silences the banner too.
+* **Which one?** With three terminals going, a chime says something finished and leaves you alt-tabbing to find out what. `vibe --notify` adds a desktop banner (`api: finished`, `web: needs you (Bash)`) and [`vibe --speak`](#-spoken-announcements-vibe---speak) adds a spoken line. Both are off by default. [Banner details below.](#-desktop-banners-vibe---notify)
+* **Say it out loud.** `vibe --speak` adds a spoken line after the chime (*"api: done."*) when two or more sessions are going. [Details below.](#-spoken-announcements-vibe---speak)
 
 <details>
 <summary><b>The rest of how sessions share one stream</b></summary>
@@ -333,6 +334,44 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **One player is shared.** Prompt two agents at once and the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
 
+### 🔔 Desktop banners: `vibe --notify`
+
+```bash
+vibe --notify       # on
+vibe --no-notify    # off again (the default)
+```
+
+A banner names the project when a turn **finishes**, **fails**, **needs you** (a permission dialog or a question) or **looks stuck**: `api: finished`, `web: needs you (Bash)`. It is saved, so it applies from your next prompt with nothing to reinstall. `vibe --status` shows it on the `notify` line, the **Alerts & extras** screen in the `vibe` menu toggles it, and `VIBE_NOTIFY=1` turns it on for one shell.
+
+- **Platforms.** macOS through `osascript`, Linux through `notify-send` (it needs a notification daemon, which most desktops have). **Windows has no banner yet**; `vibe --doctor` says so when `--notify` is on and nothing can show one. The macOS command runs without error, but how the banner looks on screen has not been checked, and the Linux path has not been run.
+- **Off by default**, because a banner is more intrusive than a sound.
+- **Safe by construction.** The project name reaches the notifier as an argument, never as part of a script, because a directory name is whatever its owner called it.
+- **Mute.** `--mute` and `VIBE_DISABLE` silence banners with everything else.
+- **Scripts.** With it on, `vibe --announce "deploy finished"` shows its text as a banner too.
+
+### 🔊 Spoken announcements: `vibe --speak`
+
+A chime says that something finished, not which project. With `--speak`, the system voice adds one short sentence after the chime:
+
+> "api: done." · "api: failed." · "web needs you: Bash." · "payments looks stuck."
+
+```bash
+vibe --speak          # on: only when two or more sessions are going
+vibe --speak-always   # on: every time, even with one session
+vibe --no-speak       # off again (the default)
+```
+
+It is saved, so it applies from your next prompt with nothing to reinstall, and `vibe --status` shows the current setting on its `speak` line. The `vibe` menu has it too: **Alerts & extras**, then Enter on "Spoken announcements" steps through off, auto and always. `VIBE_SPEAK=off` turns it off for one shell.
+
+**To hear it once:** `vibe --speak-always`, then run any agent turn (and `vibe --unmute` first if you muted).
+
+- **Why only with two sessions by default.** The sentence answers "which one?". With a single session the chime already told you, so `--speak` stays quiet and `--speak-always` is the opt-in for every time.
+- **What it says.** A project name and one of four fixed states. It never reads the agent's output, and it names a tool only if it is one of the built-in ones (`Bash`, `Edit`, ...), not an MCP tool whose name someone else chose. Names like `my-app_v2` are spoken as "my app v2".
+- **Voices.** macOS `say`, Linux `spd-say` (or `espeak-ng` / `espeak`), Windows `System.Speech` through PowerShell. Nothing is installed by VibeAudio; with no voice present it stays silent, and `vibe --doctor` says so. Verified against the real macOS `say` and stub voices; **not run on Linux or Windows**.
+- **Safety.** The text reaches the voice as an argument (an environment variable on Windows), never as part of a shell command or script, and embedded speech commands such as `[[volm 0]]` are stripped.
+- **Several at once.** Sessions that finish together speak one after another, not over each other, and the same sentence twice within five seconds is said once. Not done: merging them into "api and web: done", and lowering the music while it speaks.
+- **Muting.** `--mute` and `VIBE_DISABLE` silence it with everything else. `vibe --announce "deploy finished"` text is spoken as well when speech is on.
+
 ### As a plugin (Claude Code and Codex)
 
 If Claude Code or Codex is the agent you use, the plugin installs the same hooks with no npm step. Inside a Claude Code session, type:
@@ -601,10 +640,12 @@ vibe --announce "deploy" --outcome attention     # the "needs you" chime
 gh run watch; vibe --announce "CI finished" --exit-code $?
 ```
 
-It plays the chime for the outcome, shows the `--notify` banner if you have it on, and appends an `announced` event (`source: "cli"`, the text and the outcome) to `~/.vibeaudio/events.jsonl`, so a light or dashboard built on `--events` reacts too. It never starts or stops music and never touches an agent session. A mute silences the sound and banner but not the event, like every event.
+It plays the chime for the outcome, shows the `--notify` banner and says the text aloud if you have those on, and appends an `announced` event (`source: "cli"`, the text and the outcome) to `~/.vibeaudio/events.jsonl`, so a light or dashboard built on `--events` reacts too. It never starts or stops music and never touches an agent session. A mute silences the sound and banner but not the event, like every event.
 
 It always exits 0, so it can't turn a pipeline red, and the text is only ever passed as an argument, never through a shell. Text is capped at 200 characters, and the same text announced again within five seconds is dropped, so a loop can't machine-gun your speakers. `--no-chime` keeps it to the banner and event.
 
+To switch it off for good, for a script you can't edit: `vibe --announcements off` (or `VIBE_ANNOUNCE=off` for one shell, or the **Alerts & extras** screen in the `vibe` menu). It then does nothing and still exits 0, without even writing the event. A mute is different: it silences the sound but keeps the event.
+
 ## 🖥️ Everything Else (Claude Desktop, VS Code… via MCP)
 
 **Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration), [Qwen Code](https://github.com/QwenLM/qwen-code) [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) and [Antigravity](https://antigravity.google/docs/hooks) have hook systems, and `--install-hooks` writes to all nine** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
@@ -788,6 +829,8 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--status` | Show what's installed, running and detected, then exit | — |
 | `--doctor` | Check the setup; every problem comes with the command that fixes it. Exits 1 on a failure, so it scripts | — |
 | `--notify` / `--no-notify` | Also show a desktop banner naming the project when a turn finishes, fails or needs you. Saved to `config.json` | off |
+| `--speak` / `--speak-always` / `--no-speak` | Say which project finished, failed or needs you, after the chime: only with two or more sessions going (`--speak`), or every time (`--speak-always`). Saved to `config.json` | off |
+| `--announcements <on\|off>` | Turn `vibe --announce` on or off for good. Saved to `config.json` | on |
 | `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
 | `--statusline` | The same state as one plain line for tmux or a shell prompt (`working ×2`, `waiting: api`); prints nothing when idle | — |
 | `--state` | What every agent on the machine is doing, as one line of JSON: `idle`, `working`, `stuck` or `waiting` | — |
@@ -820,6 +863,8 @@ export VIBE_SEED=7              # Same arrangement everywhere, ignoring the dire
 export VIBE_DISABLE=1           # Mute, without uninstalling anything
 export VIBE_MUSIC=off           # Signals only: chimes and banners, no music, for this shell
 export VIBE_NOTIFY=1            # Desktop banner naming the project, for this shell
+export VIBE_SPEAK=auto           # Spoken announcements (auto, always or off), for this shell
+export VIBE_ANNOUNCE=off         # Make vibe --announce do nothing, for this shell
 export VIBE_NO_HISTORY=1        # Do not log finished turns (what --report reads)
 export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
 export VIBE_NO_FADE=1           # macOS: play with plain afplay, no fade in/out

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",

package/src/cli.js

@@ -61,7 +61,9 @@ Procedural focus music while your AI coding tools think.
   vibe --preview jazz
   gh run watch; vibe --announce "CI finished" --exit-code $?   \x1b[90m# the chime for a CI run or a script\x1b[0m
   vibe --render                  \x1b[90m# save this repo's sound as a .wav to share\x1b[0m
-  vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre)\x1b[0m
+  vibe --notify                  \x1b[90m# a desktop banner naming the project when a turn finishes or needs you (macOS, Linux)\x1b[0m
+  vibe --speak                   \x1b[90m# a voice names the project after the chime (--no-speak turns it off)\x1b[0m
+  vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre); "Alerts & extras" flips banners, speech, announce, music, mute\x1b[0m
 
 \x1b[1mOPTIONS:\x1b[0m
   -g, --genre <name>           Select genre: lofi (default), synthwave, 8bit, electronic, jazz, zen, piano, drone, rain, ocean, random
@@ -79,10 +81,13 @@ Procedural focus music while your AI coding tools think.
       --preview <genre>        Play one loop of a genre and exit
       --render [file]          Write this project's music to a .wav and exit (full scale, ignores --volume)
       --status                 Show what is installed, running and detected, then exit
-      --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes or needs you (off by default)
+      --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes, fails, needs you or looks stuck (macOS and Linux; off by default)
+      --speak | --no-speak     Also say which project finished, failed or needs you, after the chime - with two or more sessions going (off by default)
+      --speak-always           Like --speak, but every time, even with one session
+      --announcements <on|off> Turn vibe --announce on or off for good (a saved setting; on by default)
       --report [days]          How long you waited on agents, and where (default: 7 days)
       --state                  Print what every agent is doing as JSON: idle, working, stuck or waiting
-      --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit
+      --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit (spoken too when --speak is on)
       --outcome <o>            With --announce: success (default), failure or attention
       --exit-code <n>          With --announce: 0 is success, anything else failure (use $?)
       --dashboard              Serve a read-only live view of every agent on this machine, and open it
@@ -139,6 +144,8 @@ Procedural focus music while your AI coding tools think.
   VIBE_GRACE_MS=<ms>           Override the saved grace window, in ms
   VIBE_MUSIC=<on|off>          Override the saved music setting for this shell
   VIBE_NOTIFY=<on|off>         Override the saved desktop-banner setting for this shell
+  VIBE_SPEAK=<auto|always|off> Override the saved spoken-announcement setting for this shell
+  VIBE_ANNOUNCE=<on|off>       Turn vibe --announce off for this shell
   VIBE_SEED=<n>                Pin the arrangement instead of deriving it from the directory
   VIBE_DISABLE=1               Mute automatic playback without uninstalling anything
   VIBE_NO_UPDATE_CHECK=1       Never check npm for a newer version
@@ -176,6 +183,7 @@ const VALUE_FLAGS = new Set([
   "-cv", "--chime-volume",
   "--grace",
   "--music",
+  "--announcements",
   "--seed",
   "--tools",
   "--event",
@@ -227,6 +235,8 @@ function parseArgs(argv) {
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
+  let speakFlag = null;
+  let announcementsFlag = null;
   let reportDays = null;
   let stopFlag = false;
   let muteFlag = null;
@@ -428,6 +438,23 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--speak" || arg === "--speak-always" || arg === "--no-speak") {
+      speakFlag = arg === "--speak" ? "auto" : arg === "--speak-always" ? "always" : "off";
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--announcements") {
+      const value = args[i + 1].toLowerCase();
+      if (value !== "on" && value !== "off") {
+        console.error(`\x1b[31m[vibeaudio] --announcements takes on or off, not '${args[i + 1]}'.\x1b[0m`);
+        process.exit(1);
+      }
+      announcementsFlag = value === "on";
+      i += 2;
+      continue;
+    }
+
     if (arg === "--doctor") {
       doctorFlag = true;
       i += 1;
@@ -606,6 +633,8 @@ function parseArgs(argv) {
     events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
+    speak: speakFlag,
+    announcements: announcementsFlag,
     report: reportDays,
     stop: stopFlag,
     mute: muteFlag,
@@ -853,6 +882,10 @@ function printStatus() {
   console.log(`  volume    ${on(`${Math.round(volumeNow() * 100)}%`)}${source("VIBE_VOLUME", "volume")}`);
   console.log(`            ${off("change either with: vibe --genre <name> --volume <n>")}`);
   console.log(`  notify    ${hooks.notifyEnabled() ? on("on") : off("off")}${off("  desktop banner naming the project — vibe --notify / --no-notify")}`);
+  const speech = require("./speech");
+  const speakNow = speech.speakMode(process.env, loadConfig());
+  console.log(`  speak     ${speakNow === "off" ? off("off") : on(speakNow)}${off(speakNow === "off" ? "  a voice names the project after the chime — vibe --speak / --speak-always" : speakNow === "auto" ? "  only with two or more sessions — vibe --speak-always / --no-speak" : "  every time — vibe --no-speak")}${speakNow !== "off" && !speech.voiceAvailable() ? "  \x1b[33mno voice found on this machine\x1b[0m" : ""}`);
+  console.log(`  announce  ${hooks.announceEnabled() ? on("on") : "\x1b[33moff\x1b[0m"}${off(hooks.announceEnabled() ? "  vibe --announce <text> for scripts and CI — vibe --announcements off to disable" : "  vibe --announce does nothing — vibe --announcements on")}`);
 
   // Audio backend
   const backend = detect();
@@ -1059,6 +1092,22 @@ function doctorChecks() {
   if (playbackDisabled()) add("warn", "VIBE_DISABLE", `set to "${process.env.VIBE_DISABLE}" — automatic playback is off`, "unset VIBE_DISABLE");
   if (mute === null && !playbackDisabled()) add("ok", "Mute", "not muted");
   if (!musicEnabled()) add("ok", "Music", "off — chimes and banners only, by your setting (vibe --music on)");
+  if (hooks.notifyEnabled()) {
+    if (process.platform === "darwin") add("ok", "Desktop banners", "on, through osascript");
+    else if (process.platform === "linux") {
+      if (require("./interactive").isInstalled("notify-send")) add("ok", "Desktop banners", "on, through notify-send");
+      else add("warn", "Desktop banners", "on, but notify-send was not found, so no banner appears", "install libnotify (notify-send) and a notification daemon");
+    } else add("warn", "Desktop banners", "on, but this platform has no banner backend yet, so none appears", "vibe --no-notify");
+  }
+  {
+    const speech = require("./speech");
+    const mode = speech.speakMode(process.env, loadConfig());
+    if (mode !== "off") {
+      if (speech.voiceAvailable()) add("ok", "Spoken announcements", `${mode} — a voice is available`);
+      else add("warn", "Spoken announcements", `${mode}, but no voice was found, so nothing is said`,
+        process.platform === "linux" ? "install spd-say, espeak-ng or espeak" : "this system has no speech command on PATH");
+    }
+  }
 
   const pid = readDaemonPid(hooks.PID_FILE);
   if (pid === null) add("ok", "Background player", "not running");
@@ -1718,7 +1767,9 @@ function applyMenuSelection(selection, volume) {
     `\n\x1b[32m✔ VibeAudio v${pkg.version} is hooked into: ${names} (${saved.genre} @ ${saved.volume}%).\x1b[0m ` +
     `Nothing was started: open ${hooked.length > 1 ? "any of them" : "it"} whenever you like (\x1b[1m${cmds}\x1b[0m), and the music plays from your first prompt.\n` +
     `  \x1b[90mMore agents? Run vibe again for each, or vibe --install-hooks to set up every one it finds.\x1b[0m\n` +
-    `  \x1b[90mStay current: run npm i -g ${pkg.name} now and then (hooks keep working); vibe --status tells you when a newer version is out.\x1b[0m\n`
+    `  \x1b[90mStay current: run npm i -g ${pkg.name} now and then (hooks keep working); vibe --status tells you when a newer version is out.\x1b[0m\n` +
+    `  \x1b[90mOptional: vibe --speak adds a spoken line naming the project after the chime (vibe --no-speak turns it off).\x1b[0m\n` +
+    `  \x1b[90mAll commands and options: vibe --help\x1b[0m\n`
   );
   printUpdateNotice();
   return false;
@@ -1742,6 +1793,8 @@ async function run() {
     events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
+    speak: speakChange,
+    announcements: announcementsChange,
     report: reportDays,
     stop: shouldStop,
     mute: muteChange,
@@ -1779,6 +1832,23 @@ async function run() {
     }
   }
 
+  // These act on their own and then exit. With a command after them the command
+  // used to be dropped without a word and the exit code was 0, so
+  // `vibe --notify npm test && deploy` deployed without running the tests.
+  {
+    const own = muteChange !== null ? (muteChange ? "--mute" : "--unmute")
+      : notifyChange !== null ? (notifyChange ? "--notify" : "--no-notify")
+      : speakChange !== null ? (speakChange === "off" ? "--no-speak" : speakChange === "always" ? "--speak-always" : "--speak")
+      : announcementsChange !== null ? "--announcements"
+      : announceReq.text !== null ? "--announce"
+      : null;
+    if (own && cmdArgs.length > 0) {
+      console.error(`\x1b[31m[vibeaudio] ${own} does not wrap a command, so '${cmdArgs.join(" ")}' was not run.\x1b[0m ` +
+        (own === "--announce" ? `Put it after the command instead: ${cmdArgs.join(" ")}; vibe --announce "..." --exit-code $?` : `Run ${own} on its own, then the command.`));
+      process.exit(1);
+    }
+  }
+
   if (announceReq.text === null && (announceReq.outcome !== null || announceReq.exitCode !== null)) {
     console.error("\x1b[31m[vibeaudio] --outcome and --exit-code go with --announce <text>.\x1b[0m");
     process.exit(1);
@@ -1836,6 +1906,25 @@ async function run() {
     return;
   }
 
+  if (speakChange !== null) {
+    saveConfig({ speak: speakChange });
+    console.log(speakChange === "off"
+      ? "\x1b[90mSpoken announcements off.\x1b[0m"
+      : `\x1b[32m✔ Spoken announcements on${speakChange === "always" ? " (every time)" : " (when two or more sessions are going)"}.\x1b[0m After the chime, a voice says which project finished, failed or needs you.`);
+    if (speakChange !== "off" && !require("./speech").voiceAvailable()) {
+      console.log("  \x1b[33mNo voice found on this machine\x1b[0m, so nothing will be said. Linux needs spd-say, espeak-ng or espeak.");
+    }
+    return;
+  }
+
+  if (announcementsChange !== null) {
+    saveConfig({ announce: announcementsChange });
+    console.log(announcementsChange
+      ? "\x1b[32m✔ vibe --announce is on.\x1b[0m"
+      : "\x1b[90mvibe --announce is off: it now does nothing, and exits 0.\x1b[0m");
+    return;
+  }
+
   if (shouldStop) {
     const hooks = require("./hooks");
     const stopped = hooks.stopDaemon();
@@ -1939,6 +2028,8 @@ async function run() {
       process.exit(0);
     }
 
+    if (selection.settings) return; // the toggles were saved on the way out of that screen
+
     const chosenVol = selection.volume !== undefined ? selection.volume : volume;
     if (!applyMenuSelection(selection, chosenVol)) return;
 

package/src/hooks.js

@@ -17,6 +17,7 @@ const path = require("path");
 const { spawn, execFileSync } = require("child_process");
 const { AudioPlayer, loadConfig, playbackDisabled } = require("./player");
 const { recordTurn } = require("./history");
+const speech = require("./speech");
 
 const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
 const PID_FILE = path.join(STATE_DIR, "daemon.pid");
@@ -1159,6 +1160,37 @@ function notify(raw, message) {
   return banner(`${sessionLabel(parsePayload(raw))}: ${message}`);
 }
 
+/**
+ * `--announce` can be switched off for good (menu, `--announcements off`,
+ * `VIBE_ANNOUNCE=off`) for a script that cannot be edited. On unless said
+ * otherwise; env beats the saved setting.
+ */
+function announceEnabled(env = process.env, config = loadConfig()) {
+  const raw = String(env.VIBE_ANNOUNCE ?? config.announce ?? "").trim().toLowerCase();
+  return !["0", "false", "off", "no"].includes(raw);
+}
+
+/**
+ * The spoken line for a hook event (#33), after its chime. `sessionCount` is
+ * how many sessions are in flight, this one included: in `auto` mode it takes
+ * two to be worth saying, since the point is "which one?". `chimed` says a
+ * chime was started detached, so the sentence waits for it; one that already
+ * played to the end (the Stop hook plays it inline) needs no wait. Only a
+ * built-in tool is named: an MCP tool's name is third-party text.
+ */
+function speakEvent(raw, kind, sessionCount, { chimed = false, volume = 0.4, tool = "" } = {}) {
+  try {
+    if (!speech.shouldSpeak(speech.speakMode(process.env, loadConfig()), sessionCount)) return false;
+    const named = tool && Object.hasOwn(TOOL_TIERS, tool) ? tool : "";
+    return speech.speak(speech.phrase(kind, sessionLabel(parsePayload(raw)), named), {
+      delayMs: speech.chimeDelayMs(kind, chimed),
+      volume
+    });
+  } catch (e) {
+    return false; // speech must never fail the hook
+  }
+}
+
 const ANNOUNCE_FILE = path.join(STATE_DIR, "announce.json");
 const ANNOUNCE_MAX_CHARS = 200;
 const ANNOUNCE_REPEAT_MS = 5000;
@@ -1180,6 +1212,7 @@ const ANNOUNCE_OUTCOMES = ["success", "failure", "attention"];
  */
 function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre } = {}) {
   try {
+    if (!announceEnabled()) return false; // switched off: inert, event included
     const clean = String(text).replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, ANNOUNCE_MAX_CHARS);
     const now = Date.now();
     try {
@@ -1193,6 +1226,11 @@ function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null,
     banner(`${clean}${outcome === "failure" ? " (failed)" : outcome === "attention" ? " (needs you)" : ""}`);
     // Detached: a pipeline should not wait out the chime.
     if (!noChime) new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre, detach: true });
+    // The caller's own text, read after the chime. No session count to wait on:
+    // a script has no "which one", so `auto` and `always` both speak it.
+    if (speech.speakMode(process.env, loadConfig()) !== "off") {
+      speech.speak(clean, { delayMs: speech.chimeDelayMs(outcome, !noChime), volume: chimeVolume !== null ? chimeVolume : volume });
+    }
     return true;
   } catch (e) {
     return true; // a notifier must never fail the script that called it
@@ -1201,6 +1239,7 @@ function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null,
 
 function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
   const id = sessionId(payloadSession(parsePayload(raw)));
+  const active = listSessions().length; // this session included, until its file goes
   // A turn that ends while paused for the user - a denied tool that nothing
   // resumed after - still finished, so its session counts either way.
   const session = readSession(id);
@@ -1223,10 +1262,16 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   if (!others) fs.rmSync(INTENSITY_FILE, { force: true });
   if (!(tracked || wasPlaying)) return false;
   notify(raw, outcome === "failure" ? "failed" : "finished");
-  if (noChime) return false;
+  const speakVolume = chimeVolume !== null ? chimeVolume : volume;
+  if (noChime) {
+    speakEvent(raw, outcome === "failure" ? "failure" : "success", active, { volume: speakVolume });
+    return false;
+  }
 
-  // Chime plays in this short-lived hook process.
+  // Chime plays in this short-lived hook process, to the end; the sentence
+  // starts after it, so it needs no delay of its own.
   new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre });
+  speakEvent(raw, outcome === "failure" ? "failure" : "success", active, { volume: speakVolume });
   return true;
 }
 
@@ -1278,6 +1323,11 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
   if (!noChime) new AudioPlayer().stop({ playChime: true, outcome: "attention", volume, chimeVolume, detach: true });
+  speakEvent(raw, "attention", listSessions().length, {
+    chimed: !noChime && !playbackDisabled(),
+    volume: chimeVolume !== null ? chimeVolume : volume,
+    tool
+  });
   return true;
 }
 
@@ -1314,6 +1364,10 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false, musi
     // loop to put one under, so the pulse plays once on its own. Detached: the
     // agent waits on this hook.
     if (!music && !noChime) new AudioPlayer().stop({ playChime: true, outcome: "stuck", volume, chimeVolume, detach: true });
+    speakEvent(raw, "stuck", listSessions().length, {
+      chimed: !music && !noChime && !playbackDisabled(),
+      volume: chimeVolume !== null ? chimeVolume : volume
+    });
   }
 
   // An empty key is a wait that named nothing (a Notification): the next tool
@@ -1671,6 +1725,7 @@ module.exports = {
   qwenHome,
   grokHome,
   announce,
+  announceEnabled,
   recentEvents,
   emitEvent,
   ANNOUNCE_OUTCOMES,

package/src/interactive.js

@@ -3,15 +3,36 @@
  * Zero dependencies - Pure Node.js ANSI and Readline
  */
 
-const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
 const readline = require("readline");
 
-// Windows has no `which`; without this every tool shows as missing there.
-const LOOKUP_CMD = process.platform === "win32" ? "where" : "which";
-
-function isInstalled(cmd) {
-  // An argument vector, not a command string: nothing in `cmd` reaches a shell.
-  return spawnSync(LOOKUP_CMD, [cmd], { stdio: "ignore", timeout: 3000, killSignal: "SIGKILL" }).status === 0;
+/**
+ * Is `cmd` an executable on PATH? Read off the filesystem, not by asking
+ * `which`/`where`: a lookup is a process spawn, and on CI runners that spawn
+ * has hung and missed its timeout (#58), where a directory scan cannot. It
+ * also needs no `which` to exist, and nothing in `cmd` reaches a shell.
+ * A name with a separator is a path, as `which` treats it.
+ */
+function isInstalled(cmd, env = process.env) {
+  if (typeof cmd !== "string" || !cmd) return false;
+  const win = process.platform === "win32";
+  const exts = win ? String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+  const dirs = /[\\/]/.test(cmd) ? [""] : String(env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+  const hasExt = win && exts.some((e) => cmd.toLowerCase().endsWith(e.toLowerCase()));
+  for (const dir of dirs) {
+    for (const ext of hasExt ? ["", ...exts] : exts) {
+      const file = path.join(dir, cmd + ext);
+      try {
+        if (!fs.statSync(file).isFile()) continue;
+        if (!win) fs.accessSync(file, fs.constants.X_OK);
+        return true;
+      } catch (e) {
+        // Not here, or not executable: keep looking.
+      }
+    }
+  }
+  return false;
 }
 
 // Convenience only - the wrapper runs any command, and "Custom command..."
@@ -35,7 +56,8 @@ const AI_TOOLS = [
   { name: "Antigravity CLI", cmd: ["agy"], check: "agy", hookTarget: "antigravity" },
   { name: "Aider", cmd: ["aider"], check: "aider" },
   { name: "Ollama (Llama 3)", cmd: ["ollama", "run", "llama3"], check: "ollama" },
-  { name: "Custom command...", cmd: null }
+  { name: "Custom command...", cmd: null },
+  { name: "⚙️  Alerts & extras...", cmd: null, settings: true }
 ];
 
 const GENRES = [
@@ -294,6 +316,64 @@ const REACTIVE = [
   { id: true, name: "Reactive", desc: "Intensity follows the tool in use - noticeable, by design" }
 ];
 
+const NEXT_SPEAK = { off: "auto", auto: "always", always: "off" };
+
+/**
+ * The saved toggles that have no flag a person would think to look for:
+ * banners, the spoken line, `vibe --announce`, music and the mute. One screen,
+ * not a question per setting in the setup flow, which runs every time a tool
+ * is picked. Enter flips the highlighted one and the list comes back with its
+ * new value; every change is saved at once and lands on the next prompt, like
+ * `vibe --genre`. A variable set in this shell outranks the saved value, so the
+ * row says so rather than letting the toggle look dead.
+ */
+async function promptSettings() {
+  const { loadConfig, saveConfig, muteState, setMuted, musicEnabled, DEFAULT_MUTE_MINUTES } = require("./player");
+  const hooks = require("./hooks");
+  const speech = require("./speech");
+
+  for (;;) {
+    const config = loadConfig();
+    const pinned = (name) => (process.env[name] !== undefined ? ` (${name} is set in this shell and wins)` : "");
+    const speak = speech.speakMode(process.env, config);
+    const items = [
+      { id: "notify", name: "Desktop banners", value: hooks.notifyEnabled(process.env, config) ? "on" : "off",
+        desc: `name the project when a turn finishes or needs you${pinned("VIBE_NOTIFY")}` },
+      { id: "speak", name: "Spoken announcements", value: speak,
+        desc: `a voice names the project after the chime: off, auto (two or more sessions) or always${pinned("VIBE_SPEAK")}${speak !== "off" && !speech.voiceAvailable() ? " - no voice found on this machine" : ""}` },
+      { id: "announce", name: "vibe --announce", value: hooks.announceEnabled(process.env, config) ? "on" : "off",
+        desc: `the chime for CI runs and scripts${pinned("VIBE_ANNOUNCE")}` },
+      { id: "music", name: "Music", value: musicEnabled() ? "on" : "off",
+        desc: `off keeps the chimes, banners and events, and drops the music${pinned("VIBE_MUSIC")}` },
+      { id: "mute", name: "Mute", value: muteState() !== null ? "on" : "off",
+        desc: `silence everything for ${DEFAULT_MUTE_MINUTES} minutes (vibe --unmute ends it)` },
+      { id: "done", name: "Done", value: "", desc: "" }
+    ];
+
+    const chosen = await selectMenu(
+      "Alerts & extras  \x1b[0m\x1b[90m(Enter flips the highlighted one)\x1b[0m",
+      items,
+      (item, num) => item.id === "done"
+        ? `${num}. ${item.name}`
+        : `${num}. ${item.name}: ${item.value === "off" ? "\x1b[33moff\x1b[0m" : `\x1b[32m${item.value}\x1b[0m`} \x1b[90m— ${item.desc}\x1b[0m`
+    );
+
+    if (chosen.id === "done") break;
+    if (chosen.id === "notify") saveConfig({ notify: chosen.value !== "on" });
+    else if (chosen.id === "speak") saveConfig({ speak: NEXT_SPEAK[chosen.value] });
+    else if (chosen.id === "announce") saveConfig({ announce: chosen.value !== "on" });
+    else if (chosen.id === "music") saveConfig({ music: chosen.value !== "on" });
+    else if (chosen.id === "mute") {
+      if (chosen.value === "on") setMuted(false);
+      else {
+        setMuted(true, DEFAULT_MUTE_MINUTES);
+        hooks.stopDaemon({ keepSessions: true }); // silence what is playing now, not just the next prompt
+      }
+    }
+  }
+  console.log("\n\x1b[32m✔ Saved.\x1b[0m Changes apply from your next prompt. Nothing was started.\n");
+}
+
 /**
  * `hooksInstalledFor` is asked about the tool the user picked, not about
  * Claude: the caller cannot know which tool that is until this menu runs, and
@@ -323,6 +403,11 @@ async function promptInteractive({ hooksInstalledFor = () => false } = {}) {
     }
   );
 
+  if (selectedTool.settings) {
+    await promptSettings();
+    return { settings: true };
+  }
+
   let finalCmd = selectedTool.cmd;
   if (!finalCmd) {
     finalCmd = await promptCustomCommand();
@@ -387,4 +472,4 @@ async function promptInteractive({ hooksInstalledFor = () => false } = {}) {
   };
 }
 
-module.exports = { promptInteractive, tokenizeCommand, isInstalled, hookTargetOf, playPreview, stopPreview, AI_TOOLS };
+module.exports = { promptInteractive, promptSettings, tokenizeCommand, isInstalled, hookTargetOf, playPreview, stopPreview, AI_TOOLS };

package/src/speech.js

@@ -0,0 +1,260 @@
+/**
+ * Spoken announcements (#33): the sentence after the chime that says *which*
+ * project finished, failed or needs you. A chime says that something happened
+ * and leaves you alt-tabbing to find out what.
+ *
+ * Opt-in (`--speak`, `speak` in config.json, `VIBE_SPEAK`). Three modes:
+ * `auto` speaks only when two or more sessions are going - the one case where
+ * the chime cannot answer "which one?"; with a single session the sentence
+ * would repeat what the chime already said. `always` speaks every time.
+ *
+ * The voice is the operating system's own (`say`, `spd-say` / `espeak`,
+ * `System.Speech`), so nothing is installed and nothing leaves the machine.
+ * The words are fixed: a project name and a state, never the agent's output.
+ * The project name is user-controlled text, so it travels as argv (or an
+ * environment variable on Windows), never spliced into a shell or a script.
+ *
+ * Speech runs in a detached process of its own (`node speech.js --run ...`):
+ * the agent waits on the hook, and the sentence has to start after the chime,
+ * not on top of it. That process takes a lock for the length of the sentence,
+ * so sessions that finish together speak one after another, not over each
+ * other. Merging them into one sentence is not done.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
+const LOCK_FILE = path.join(STATE_DIR, "speech.lock");
+const LAST_FILE = path.join(STATE_DIR, "speech.json");
+
+const SPEECH_MAX_CHARS = 200;
+const REPEAT_MS = 5000; // the same sentence inside this window is dropped
+const LOCK_STALE_MS = 30000; // a holder this old died without releasing
+const LOCK_WAIT_MS = 20000; // a queue this long is not worth joining
+const SPEAK_TIMEOUT_MS = 15000; // a voice that hangs is killed
+
+// How long each chime plays, plus a breath: the sentence starts after it.
+const CHIME_MS = { success: 1600, failure: 1800, attention: 1300, stuck: 1800 };
+const CHIME_GAP_MS = 150;
+
+const MODES = ["off", "auto", "always"];
+
+function parseMode(value) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (raw === "always") return "always";
+  if (["1", "true", "on", "yes", "auto"].includes(raw)) return "auto";
+  return "off";
+}
+
+/** Env beats the saved setting, like every other one. */
+function speakMode(env = process.env, config = {}) {
+  return parseMode(env.VIBE_SPEAK ?? config.speak);
+}
+
+/** Whether to speak now: `auto` needs two or more sessions to be worth it. */
+function shouldSpeak(mode, sessionCount) {
+  return mode === "always" || (mode === "auto" && sessionCount >= 2);
+}
+
+/**
+ * Text that is safe to hand a voice: no control characters, and no embedded
+ * speech commands. macOS `say` reads `[[volm 0]]` and its kin out of the text,
+ * so a project directory called that would otherwise steer the voice.
+ */
+function cleanText(text, max = SPEECH_MAX_CHARS) {
+  let out = String(text).replace(/[\u0000-\u001f\u007f]+/g, " ");
+  while (/\[\[[^\]]*\]\]/.test(out)) out = out.replace(/\[\[[^\]]*\]\]/g, " ");
+  out = out.replace(/\[\[|\]\]/g, " "); // what nesting left behind
+  return out.replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+/** "my-app_v2" reads better as "my app v2" than as "my dash app underscore v2". */
+function speakableLabel(label) {
+  return cleanText(String(label).replace(/[-_.]+/g, " "), 60) || "a session";
+}
+
+/**
+ * The fixed sentences. `tool` is only passed for a built-in tool name: an MCP
+ * tool's name is third-party text, and the line never speaks it.
+ */
+function phrase(kind, label, tool = "") {
+  const who = speakableLabel(label);
+  const what = cleanText(String(tool).replace(/_/g, " "), 40);
+  switch (kind) {
+    case "failure": return `${who}: failed.`;
+    case "attention": return what ? `${who} needs you: ${what}.` : `${who} needs you.`;
+    case "stuck": return `${who} looks stuck.`;
+    default: return `${who}: done.`;
+  }
+}
+
+const POWERSHELL_SCRIPT =
+  "Add-Type -AssemblyName System.Speech; " +
+  "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer; " +
+  "$s.Volume = [int]$env:VIBE_SPEECH_VOLUME; " +
+  "$s.Speak($env:VIBE_SPEECH_TEXT)";
+
+/**
+ * The command that speaks `text`, or null where this machine has no voice.
+ * `volume` is VibeAudio's 0-1 setting where the voice has a way to take it:
+ * macOS `say` follows the system volume unless told otherwise, and `spd-say`
+ * has no usable scale, so it speaks at its own level.
+ */
+function voiceCommand(platform, text, volume = 0.4, has = () => false) {
+  const v = Math.max(0.05, Math.min(1, Number(volume) || 0.4));
+  if (platform === "darwin") {
+    return has("say") ? { cmd: "say", args: ["--", `[[volm ${v.toFixed(2)}]] ${text}`] } : null;
+  }
+  if (platform === "win32") {
+    return {
+      cmd: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-Command", POWERSHELL_SCRIPT],
+      env: { VIBE_SPEECH_TEXT: text, VIBE_SPEECH_VOLUME: String(Math.round(v * 100)) }
+    };
+  }
+  if (has("spd-say")) return { cmd: "spd-say", args: ["-w", "--", text] };
+  for (const cmd of ["espeak-ng", "espeak"]) {
+    if (has(cmd)) return { cmd, args: ["-a", String(Math.round(v * 200)), "--", text] };
+  }
+  return null;
+}
+
+function currentVoice(text, volume) {
+  const { isInstalled } = require("./interactive");
+  return voiceCommand(process.platform, text, volume, isInstalled);
+}
+
+/** `--doctor`: is there anything to speak with here? */
+function voiceAvailable() {
+  return currentVoice("test", 0.4) !== null;
+}
+
+/**
+ * Hand a sentence to a detached process that waits `delayMs` (for the chime),
+ * takes its turn on the lock, and speaks. Returns false when nothing was
+ * started. Never throws and never waits: the caller is a hook.
+ */
+function speak(text, { delayMs = 0, volume = 0.4 } = {}) {
+  try {
+    const { playbackDisabled } = require("./player");
+    if (playbackDisabled()) return false; // a mute means quiet, speech included
+    const clean = cleanText(text);
+    if (!clean || !currentVoice(clean, volume)) return false;
+    const child = spawn(process.execPath, [__filename, "--run", String(Math.max(0, Math.round(delayMs))), String(volume), clean], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** How long to wait so a sentence starts after the chime that was just played. */
+function chimeDelayMs(outcome, played = true) {
+  return played ? (CHIME_MS[outcome] || CHIME_MS.success) + CHIME_GAP_MS : 0;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+/** One speaker at a time across processes: exclusive create, with a stale check. */
+async function acquireLock(waitMs = LOCK_WAIT_MS) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      fs.writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: "wx" });
+      return () => fs.rmSync(LOCK_FILE, { force: true });
+    } catch (e) {
+      if (e.code !== "EEXIST") return null;
+    }
+    try {
+      const held = JSON.parse(fs.readFileSync(LOCK_FILE, "utf8"));
+      if (Date.now() - held.at > LOCK_STALE_MS || !pidAlive(held.pid)) fs.rmSync(LOCK_FILE, { force: true });
+    } catch (e) {
+      // Unreadable (being written, or just removed): look again.
+    }
+    if (Date.now() > deadline) return null;
+    await sleep(100);
+  }
+}
+
+function speakNow(text, volume) {
+  return new Promise((resolve) => {
+    const voice = currentVoice(text, volume);
+    if (!voice) return resolve(false);
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(ok);
+    };
+    let child;
+    try {
+      child = spawn(voice.cmd, voice.args, { stdio: "ignore", env: { ...process.env, ...(voice.env || {}) } });
+    } catch (e) {
+      return resolve(false);
+    }
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch (e) { /* gone already */ }
+      finish(false);
+    }, SPEAK_TIMEOUT_MS);
+    child.on("error", () => finish(false));
+    child.on("close", (code) => finish(code === 0));
+  });
+}
+
+/** The body of the detached process. */
+async function run(delayMs, volume, text) {
+  const { playbackDisabled } = require("./player");
+  await sleep(delayMs);
+  const release = await acquireLock();
+  if (!release) return; // could not get a turn: drop it rather than talk over someone
+  try {
+    if (playbackDisabled()) return; // muted while it waited
+    try {
+      const last = JSON.parse(fs.readFileSync(LAST_FILE, "utf8"));
+      if (last.text === text && Date.now() - last.at < REPEAT_MS) return;
+    } catch (e) { /* first one, or unreadable: nothing to compare */ }
+    fs.writeFileSync(LAST_FILE, JSON.stringify({ text, at: Date.now() }));
+    await speakNow(text, volume);
+  } finally {
+    release();
+  }
+}
+
+if (require.main === module && process.argv[2] === "--run") {
+  run(Number(process.argv[3]) || 0, Number(process.argv[4]) || 0.4, String(process.argv[5] || ""))
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}
+
+module.exports = {
+  MODES,
+  speakMode,
+  shouldSpeak,
+  cleanText,
+  phrase,
+  voiceCommand,
+  voiceAvailable,
+  speak,
+  chimeDelayMs,
+  acquireLock,
+  LOCK_FILE,
+  LAST_FILE,
+  SPEECH_MAX_CHARS
+};