vibeaudio 0.19.0 → 0.20.1

package/README.md

@@ -1,11 +1,13 @@
 # 🎧 VibeAudio
 
 <p align="center">
-  <img src="docs/og.png?v=2" alt="VibeAudio — Focus music while your AI codes" width="720">
+  <img src="docs/og.png?v=3" alt="VibeAudio — Focus music while your AI codes" width="720">
 </p>
 
 [![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/vibeaudio)](https://www.npmjs.com/package/vibeaudio) [![license](https://img.shields.io/npm/l/vibeaudio)](LICENSE) [![node](https://img.shields.io/node/v/vibeaudio)](https://nodejs.org) [![downloads/month](https://img.shields.io/npm/dm/vibeaudio)](https://npm-stat.com/charts.html?package=vibeaudio) [![M8ven Score](https://m8ven.ai/badge/mcp/kiril6/vibeaudio)](https://m8ven.ai/mcp/kiril6/vibeaudio?s=readme)
 
+<a href="https://www.producthunt.com/products/vibeaudio/reviews/new?utm_source=badge-product_review&utm_medium=badge&utm_source=badge-vibeaudio" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/product_review.svg?product_id=1317092&theme=light" alt="VibeAudio - Focus&#0032;music&#0032;while&#0032;your&#0032;AI&#0032;codes&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
 > Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Antigravity, Aider — and any terminal command.
@@ -147,7 +149,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 +316,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 +336,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:
@@ -455,6 +496,8 @@ plus where the time went by project and, for windows up to two weeks, by day. "Y
 
 </details>
 
+**Share it:** `vibe --report --card` (or `--report 30 --card`) saves the same totals as a square image to `~/.vibeaudio/card.png` (`--out <path>` writes it elsewhere). It shows your time with agents, turns, typical and longest turn, a bar per day, the agents VibeAudio hooks into, and where to get it. It carries totals only — never a project name — and is written locally, never uploaded: attach it to a post yourself. The PNG needs macOS; elsewhere you get the SVG, which any browser opens. One file, replaced on each run.
+
 ### The chime is in the music's key
 
 The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
@@ -601,10 +644,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,7 +833,10 @@ 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 |
+| `--card [--out <path>]` | With `--report`: the totals as a shareable image - PNG on macOS, SVG anywhere - saved to `~/.vibeaudio/card.png`, replaced each run | off |
 | `--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` | — |
 | `--events` | Stream agent state changes as JSON lines, starting with the current state, until stopped | — |
@@ -820,6 +868,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
@@ -995,3 +1045,5 @@ Support development: <a href="https://ko-fi.com/K3K2X0ERJ"><img src="https://ko-
 
 ## 📄 License
 MIT © 2026
+
+VibeAudio is not affiliated with or endorsed by Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code, Windsurf, Antigravity or any other tool it works with. Their names are used only to say what it works with.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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/card.js

@@ -0,0 +1,129 @@
+/**
+ * `vibe --report --card`: the report as a picture you can post. The SVG is
+ * built as a string (pure, no I/O, so a test can read it); macOS also gets a
+ * PNG through Quick Look, since every other platform would need a rasterizer
+ * and this package has no dependencies.
+ *
+ * It carries totals only, never a project name or path: a card is made to be
+ * shared, and a project is the user's to name. It is written locally and
+ * sent nowhere.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { formatDuration, summarize, dayTotals } = require("./history");
+const { TARGETS } = require("./hooks");
+
+const CARD_DIR = path.join(os.homedir(), ".vibeaudio");
+// Square, because Quick Look scales a thumbnail to fit its height and crops the rest.
+const SIZE = 1080;
+const MAX_BARS = 14;
+
+/** The card's SVG for a non-empty list of turns over the last `days` days. */
+function renderCard(turns, days, now = Date.now()) {
+  const s = summarize(turns);
+  const rows = dayTotals(turns, Math.min(days, MAX_BARS), now);
+  const peak = Math.max(...rows.map((r) => r.ms)) || 1;
+  const period = days === 1 ? "today" : `last ${days} days`;
+
+  const slot = 920 / rows.length;
+  const barW = Math.min(46, slot * 0.6);
+  const bars = rows.map((r, i) => {
+    const h = r.ms ? Math.max(10, Math.round((r.ms / peak) * 160)) : 4;
+    const x = Math.round(80 + i * slot + (slot - barW) / 2);
+    return `<rect x="${x}" y="${780 - h}" width="${barW}" height="${h}" rx="${Math.min(barW / 2, 12)}" fill="${r.ms ? "url(#bar)" : "#3c2a5e"}"/>`;
+  }).join("") + rows.map((r, i) =>
+    `<text x="${Math.round(80 + i * slot + slot / 2)}" y="806" class="d" text-anchor="middle">${r.date.toLocaleDateString("en-US", { weekday: "short" })}</text>`).join("");
+
+  // Pills, not the agents' logos: those are their owners' marks, and a pill
+  // from TARGETS cannot fall out of step with what we actually hook into.
+  let cx = 80;
+  let cy = 864;
+  const pills = Object.values(TARGETS).map(({ name }) => {
+    const w = Math.round(name.length * 12 + 34);
+    if (cx + w > 1000) { cx = 80; cy += 50; }
+    const out = `<rect x="${cx}" y="${cy}" width="${w}" height="38" rx="10" fill="#120b1f" stroke="#3c2a5e" stroke-width="2"/><text x="${cx + w / 2}" y="${cy + 26}" class="c" text-anchor="middle">${name}</text>`;
+    cx += w + 12;
+    return out;
+  }).join("");
+
+  const stat = (x, value, label) =>
+    `<text x="${x}" y="552" class="v">${value}</text><text x="${x}" y="586" class="l">${label}</text>`;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SIZE} ${SIZE}" width="${SIZE}" height="${SIZE}">
+<defs>
+<linearGradient id="hero" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#ff2e97"/><stop offset="1" stop-color="#ffb454"/></linearGradient>
+<linearGradient id="bar" x1="0" y1="1" x2="0" y2="0"><stop offset="0" stop-color="#a855f7"/><stop offset="0.55" stop-color="#ff2e97"/><stop offset="1" stop-color="#ffb454"/></linearGradient>
+<radialGradient id="gp" cx="0.08" cy="0.04" r="0.65"><stop offset="0" stop-color="#ff2e97" stop-opacity="0.24"/><stop offset="1" stop-color="#ff2e97" stop-opacity="0"/></radialGradient>
+<radialGradient id="gc" cx="0.98" cy="0.06" r="0.55"><stop offset="0" stop-color="#00e5ff" stop-opacity="0.16"/><stop offset="1" stop-color="#00e5ff" stop-opacity="0"/></radialGradient>
+<radialGradient id="gv" cx="0.5" cy="1.02" r="0.7"><stop offset="0" stop-color="#a855f7" stop-opacity="0.16"/><stop offset="1" stop-color="#a855f7" stop-opacity="0"/></radialGradient>
+<clipPath id="card"><rect width="${SIZE}" height="${SIZE}" rx="48"/></clipPath>
+<filter id="glow" x="-20%" y="-40%" width="140%" height="180%"><feGaussianBlur stdDeviation="7" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter>
+<style>text{font-family:ui-monospace,'SF Mono',Menlo,Monaco,monospace;fill:#f2ecff}.t{font-size:60px;font-weight:800}.h{font-size:84px;font-weight:800}.v{font-size:44px;font-weight:700}.l{font-size:21px;fill:#b3a3d6}.s{font-size:26px;fill:#b3a3d6}.m{font-size:30px;font-weight:800;letter-spacing:2px}.f{font-size:20px;fill:#9584be}.c{font-size:20px}.u{font-size:23px;font-weight:700;fill:#ff2e97}.n{font-size:14px;fill:#8272ad}.d{font-size:16px;fill:#9584be}.i{font-size:20px;font-weight:700;fill:#00e5ff}</style>
+</defs>
+<g clip-path="url(#card)"><rect width="${SIZE}" height="${SIZE}" fill="#07050d"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gp)"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gc)"/><rect width="${SIZE}" height="${SIZE}" fill="url(#gv)"/></g>
+<rect x="3" y="3" width="${SIZE - 6}" height="${SIZE - 6}" rx="46" fill="none" stroke="#3c2a5e" stroke-width="3"/>
+<g transform="translate(80 78) scale(0.17) translate(-60 -100)"><path d="M120 300V272a136 136 0 0 1 272 0V300" fill="none" stroke="url(#bar)" stroke-width="30" stroke-linecap="round"/><rect x="86" y="286" width="76" height="136" rx="32" fill="url(#bar)"/><rect x="350" y="286" width="76" height="136" rx="32" fill="url(#bar)"/><g fill="#00e5ff"><rect x="212" y="326" width="22" height="56" rx="11"/><rect x="245" y="296" width="22" height="116" rx="11"/><rect x="278" y="318" width="22" height="72" rx="11"/></g></g>
+<text x="164" y="126" class="m">VIBE<tspan fill="#ff2e97" style="fill:#ff2e97" filter="url(#glow)">AUDIO</tspan></text>
+<text x="1000" y="124" class="u" text-anchor="end">kiril6.github.io/vibeaudio</text>
+<text x="80" y="224" class="t" filter="url(#glow)">Focus music</text>
+<text x="80" y="298" class="t" filter="url(#glow)">while your <tspan style="fill:#00e5ff">AI</tspan> codes.</text>
+<text x="80" y="420" class="h" style="fill:url(#hero)">${formatDuration(s.waited)}</text>
+<text x="80" y="462" class="s">with my <tspan style="fill:#00e5ff" font-weight="800">AI</tspan> agents working · ${period}</text>
+${stat(80, String(s.count), s.count === 1 ? "turn" : "turns")}${stat(360, formatDuration(s.median), "typical turn")}${stat(680, formatDuration(s.longest.ms), "longest turn")}
+${bars}
+${rows.length < days ? `<text x="1000" y="842" class="f" text-anchor="end">bars: last ${rows.length} days</text>` : ""}
+<text x="80" y="842" class="f">works as a hook for</text>
+${pills}
+<rect x="80" y="972" width="578" height="52" rx="10" fill="#0a1a22" stroke="#00e5ff" stroke-opacity="0.45" stroke-width="2"/>
+<text x="100" y="1005" class="i">npm i -g vibeaudio &amp;&amp; vibe --install-hooks</text>
+<text x="1000" y="1000" class="n" text-anchor="end">Not affiliated with or endorsed</text>
+<text x="1000" y="1020" class="n" text-anchor="end">by the tools named.</text>
+</svg>
+`;
+}
+
+/** Write `file` by renaming a temp file into place, so an interrupted run leaves no torn card. */
+function writeAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Writes the card as one fixed file, replaced on every run, so nothing
+ * accumulates. `out` is a user-chosen path (kept as given); without it the card
+ * lives in ~/.vibeaudio. Returns the SVG path and the PNG path (null off macOS
+ * or when Quick Look could not render).
+ */
+function writeCard(turns, days, { out = null, now = Date.now(), dir = CARD_DIR } = {}) {
+  const base = out ? path.resolve(out.replace(/\.(svg|png)$/i, "")) : path.join(dir, "card");
+  fs.mkdirSync(path.dirname(base), { recursive: true });
+  const svgPath = `${base}.svg`;
+  writeAtomic(svgPath, renderCard(turns, days, now));
+
+  let pngPath = null;
+  if (process.platform === "darwin") {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "vibe-card-"));
+    try {
+      // SIGKILL as well as a timeout: a hung system helper ignores SIGTERM.
+      const r = spawnSync("qlmanage", ["-t", "-s", String(SIZE), "-o", scratch, svgPath], { stdio: "ignore", timeout: 15000, killSignal: "SIGKILL" });
+      const rendered = path.join(scratch, `${path.basename(svgPath)}.png`);
+      if (r.status === 0 && fs.existsSync(rendered)) {
+        // Copy, not rename: the scratch dir and `--out` may be on different volumes.
+        const png = `${base}.png`;
+        writeAtomic(png, fs.readFileSync(rendered));
+        pngPath = png;
+      }
+    } catch (e) {
+      pngPath = null;
+    } finally {
+      fs.rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+  return { svgPath, pngPath };
+}
+
+module.exports = { CARD_DIR, renderCard, writeCard };

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,14 @@ 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)
+      --card [--out <path>]    With --report: save the totals as an image (PNG on macOS, SVG anywhere) to ~/.vibeaudio/card.*, replaced each run
       --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 +145,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,13 +184,15 @@ const VALUE_FLAGS = new Set([
   "-cv", "--chime-volume",
   "--grace",
   "--music",
+  "--announcements",
   "--seed",
   "--tools",
   "--event",
   "--announce",
   "--outcome",
   "--exit-code",
-  "--port"
+  "--port",
+  "--out"
 ]);
 
 function parseArgs(argv) {
@@ -227,7 +237,11 @@ function parseArgs(argv) {
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
+  let speakFlag = null;
+  let announcementsFlag = null;
   let reportDays = null;
+  let cardFlag = false;
+  let cardOut = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -422,12 +436,41 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--card") {
+      cardFlag = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--out") {
+      cardOut = args[i + 1];
+      i += 2;
+      continue;
+    }
+
     if (arg === "--notify" || arg === "--no-notify") {
       notifyFlag = arg === "--notify";
       i += 1;
       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,7 +649,11 @@ function parseArgs(argv) {
     events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
+    speak: speakFlag,
+    announcements: announcementsFlag,
     report: reportDays,
+    card: cardFlag,
+    cardOut,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -853,6 +900,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 +1110,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");
@@ -1076,15 +1143,6 @@ function doctorChecks() {
   return checks;
 }
 
-/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
-function formatDuration(ms) {
-  const s = Math.round(ms / 1000);
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
-  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
-}
-
 /**
  * The summary of ~/.vibeaudio/history.jsonl. "You waited" is the agent's own
  * working time - a turn's length minus the stretches it spent blocked on a
@@ -1094,7 +1152,7 @@ function formatDuration(ms) {
  * over RETURN_WINDOW_MS read as breaks and left out.
  */
 function printReport(days, now = Date.now()) {
-  const { readTurns, returnTimes } = require("./history");
+  const { readTurns, returnTimes, formatDuration, working, summarize, dayTotals } = require("./history");
   const turns = readTurns(days, now);
   const dim = (s) => `\x1b[90m${s}\x1b[0m`;
   const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -1108,14 +1166,7 @@ function printReport(days, now = Date.now()) {
     return;
   }
 
-  const working = (t) => t.ms - (t.blockedMs || 0);
-  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
-  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
-  const median = sorted[Math.floor(sorted.length / 2)];
-  const longest = turns.reduce((a, b) => (b.ms > a.ms ? b : a));
-  const failed = turns.filter((t) => t.outcome === "failure").length;
-  const waitedOnAgents = sum(turns.map(working));
-  const blocked = sum(turns.map((t) => t.blockedMs || 0));
+  const { failed, waited: waitedOnAgents, blocked, median, longest } = summarize(turns);
 
   // Two projects called `api` under different parents stay apart.
   const names = new Map();
@@ -1162,15 +1213,9 @@ function printReport(days, now = Date.now()) {
 
   if (days <= 14) {
     console.log(`\n${bold("By day")}`);
-    const byDay = new Map();
-    for (const t of turns) {
-      const key = new Date(t.at).toLocaleDateString("en-CA");
-      byDay.set(key, (byDay.get(key) || 0) + working(t));
-    }
-    const maxDay = Math.max(...byDay.values()) || 1;
-    for (let d = days - 1; d >= 0; d--) {
-      const date = new Date(now - d * 86400000);
-      const ms = byDay.get(date.toLocaleDateString("en-CA")) || 0;
+    const rows = dayTotals(turns, days, now);
+    const maxDay = Math.max(...rows.map((r) => r.ms)) || 1;
+    for (const { date, ms } of rows) {
       const name = `${date.toLocaleDateString("en-US", { weekday: "short" })} ${date.getDate()}`;
       console.log(`  ${name.padEnd(8)}${(ms ? formatDuration(ms) : "—").padStart(8)}  ${"█".repeat(ms ? Math.max(1, Math.round((ms / maxDay) * 14)) : 0)}`);
     }
@@ -1178,6 +1223,31 @@ function printReport(days, now = Date.now()) {
   console.log();
 }
 
+/** `--report --card`: the report as an image, written locally and never uploaded. */
+function printCard(days, out) {
+  const { readTurns } = require("./history");
+  const turns = readTurns(days, Date.now());
+  if (!turns.length) {
+    console.log(`\n  No turns recorded in the last ${days === 1 ? "day" : `${days} days`}, so there is nothing to draw yet.`);
+    console.log(`\x1b[90m  Turns are logged when your agent's hooks fire (vibe --install-hooks).\x1b[0m\n`);
+    return;
+  }
+  const { writeCard } = require("./card");
+  let written;
+  try {
+    written = writeCard(turns, days, { out });
+  } catch (e) {
+    console.error(`\x1b[31m[vibeaudio] Could not write the card: ${e.message}\x1b[0m`);
+    process.exit(1);
+  }
+  const { formatDuration, summarize } = require("./history");
+  const shown = written.pngPath || written.svgPath;
+  console.log(`\n  Card saved: \x1b[1m${shown}\x1b[0m`);
+  if (!written.pngPath) console.log(`\x1b[90m  PNG needs macOS; the SVG opens in any browser.\x1b[0m`);
+  console.log(`\x1b[90m  Totals only - no project names. It stays on this machine; attach it to a post yourself.\x1b[0m`);
+  console.log(`\n  ${formatDuration(summarize(turns).waited)} with my AI agents working, with focus music from VibeAudio: https://kiril6.github.io/vibeaudio  (npm i -g vibeaudio && vibe --install-hooks)\n`);
+}
+
 function printDoctor() {
   const mark = { ok: "\x1b[32m✔\x1b[0m", warn: "\x1b[33m!\x1b[0m", fail: "\x1b[31m✘\x1b[0m" };
   const checks = doctorChecks();
@@ -1718,7 +1788,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,7 +1814,11 @@ async function run() {
     events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
+    speak: speakChange,
+    announcements: announcementsChange,
     report: reportDays,
+    card: cardFlag,
+    cardOut,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1779,6 +1855,24 @@ 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"
+      : cardFlag ? "--card"
+      : 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 +1930,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();
@@ -1890,6 +2003,12 @@ async function run() {
     return;
   }
 
+  if (cardOut !== null && !cardFlag) {
+    console.error("\x1b[31m[vibeaudio] --out goes with --card.\x1b[0m");
+    process.exit(1);
+  }
+  if (cardFlag) return printCard(reportDays ?? 7, cardOut);
+
   if (reportDays !== null) {
     return printReport(reportDays);
   }
@@ -1939,6 +2058,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/history.js

@@ -85,4 +85,49 @@ function returnTimes(turns) {
   return gaps;
 }
 
-module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes };
+/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
+}
+
+/** A turn's working time: its length minus the stretches it spent blocked on you. */
+const working = (t) => t.ms - (t.blockedMs || 0);
+
+/**
+ * The headline numbers of a non-empty list of turns. `--report` and
+ * `--report --card` both read these, so the card can never disagree with the
+ * text it is a picture of.
+ */
+function summarize(turns) {
+  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
+  return {
+    count: turns.length,
+    failed: turns.filter((t) => t.outcome === "failure").length,
+    waited: sum(turns.map(working)),
+    blocked: sum(turns.map((t) => t.blockedMs || 0)),
+    median: sorted[Math.floor(sorted.length / 2)],
+    longest: turns.reduce((a, b) => (b.ms > a.ms ? b : a))
+  };
+}
+
+/** Working time per calendar day for the last `days` days, oldest first. */
+function dayTotals(turns, days, now = Date.now()) {
+  const byDay = new Map();
+  for (const t of turns) {
+    const key = new Date(t.at).toLocaleDateString("en-CA");
+    byDay.set(key, (byDay.get(key) || 0) + working(t));
+  }
+  const out = [];
+  for (let d = days - 1; d >= 0; d--) {
+    const date = new Date(now - d * 86400000);
+    out.push({ date, ms: byDay.get(date.toLocaleDateString("en-CA")) || 0 });
+  }
+  return out;
+}
+
+module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes, formatDuration, working, summarize, dayTotals };

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
+};