vibeaudio 0.15.0 → 0.16.0

package/README.md

@@ -45,6 +45,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
 * 💓 **A heartbeat when an agent looks stuck.** If 4 of a session's last 8 tool calls fail — the test-edit-test loop that goes nowhere — a soft pulse on the music's tonic joins the music until things start passing again. It's rare by design: on 4,497 real turns it fired in under 1%.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
+* 🔕 **Signals without the music.** `vibe --music off` keeps the done, failed and "needs you" chimes, banners and the state stream, and drops the music. For people who bring their own, or share an office. ([details](#signals-only-vibe---music-off))
 * 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf and Antigravity**; MCP for **Claude Desktop**; the wrapper (`vibe <command>`) for anything else.
 
 <details>
@@ -418,6 +419,22 @@ Removing them is one command:
 vibe --uninstall-hooks
 ```
 
+### Signals only: `vibe --music off`
+
+VibeAudio does two jobs: music while an agent works, and signals (the done, failed and "needs you" chimes, banners, the stuck alert, `--events`). If you only want the second:
+
+```bash
+vibe --music off      # signals only
+vibe --music on       # music back, in the genre you had
+vibe --music off --here   # this project only
+```
+
+It's a setting of its own, saved to `config.json` like genre and volume, so your genre is still there when you turn music back on. Like the others, a flag beats `VIBE_MUSIC=off`, which beats `--here`, which beats the global value, and installed hooks pick it up on the next prompt.
+
+With music off, hooks still track every turn: the chimes, `--notify` banners, `--state`, `--events` and `--report` behave exactly as before, and no background player is started. The wrapper (`vibe npm test`) stays silent while it runs and chimes when a run that outlasted the grace window ends, so it becomes "tell me when it's done". MCP's `vibe_play` tells the model that music is off rather than claiming it started. `vibe --status` and `vibe --doctor` show the setting.
+
+Two things differ from music on. The stuck heartbeat is a layer on the music, so with music off it plays once on its own, the same two soft beats, when a session crosses into stuck (you also get the `stuck` event and, with `--notify`, the banner). And turning music off while something is playing doesn't cut it: `vibe --stop` does, or it ends with the current turn.
+
 ### Know where your time goes: `vibe --report`
 
 Hooks log each finished turn — which project, how long, how it ended, and how much of it the agent spent blocked on a dialog of yours — to `~/.vibeaudio/history.jsonl`. `vibe --report` (or `--report 30`) totals it:
@@ -509,9 +526,20 @@ Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with
 
 #### 📟 Status Bar & Desktop Integrations
 
-**tmux status bar** — show overall agent state (`waiting`, `stuck`, `working`, or `idle`):
+**`vibe --statusline`** prints the same state as one plain line, with no `jq`, and **nothing at all when idle**, so a prompt segment disappears. It shows the most urgent state, with a count when several sessions are in it, and names the project when one is waiting on you:
+
+```
+working
+working ×2
+stuck
+waiting: api
+```
+
+It is plain text on purpose: tmux and Starship do their own styling. It doesn't run `ps` and doesn't change when you're muted.
+
+**tmux status bar:**
 ```bash
-set -g status-right '#(vibe --state | jq -r .status)'
+set -g status-right '#(vibe --statusline)'
 ```
 
 **macOS speech alert** — announce out loud whenever an agent stops to ask for your input:
@@ -522,9 +550,13 @@ vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | whil
 **Starship prompt** — custom indicator in `~/.config/starship.toml`:
 ```toml
 [custom.vibe]
-command = "vibe --state | jq -r 'if .status != \"idle\" then \"🎧 \" + .status else \"\" end'"
+command = "vibe --statusline"
 when = "command -v vibe >/dev/null"
+format = "([🎧 $output ]($style))"
 ```
+The parentheses matter: Starship hides a group whose variables are empty, so the 🎧 disappears with the text when idle. Put the icon in a `symbol` instead and it shows all the time. `vibe --statusline` takes about 40 ms, so running it on every prompt is fine.
+
+*Run on tmux 3.x and Starship 1.26.0, macOS arm64, Node 24: both showed `working`, `working ×2` and `waiting: web` as sessions started and waited, and nothing when idle. Not run on Linux or Windows.*
 
 The stream is a local file (`~/.vibeaudio/events.jsonl`, rotated at 256 KB), so it never leaves your machine. It keeps updating while you're muted, because a mute silences sound and a light isn't sound. The `v` field is the format version, and any breaking change will increment it.
 
@@ -698,6 +730,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--grace <ms>` | Silence window before music starts | `1500` |
 | `--here` | With a saved setting: this directory tree only, not everywhere | off |
 | `--seed <n>` | Force a specific arrangement | derived from the project directory |
+| `--music <on\|off>` | `off` keeps the chimes, banners and events and drops the music. With no command after it, saves it as a setting. `--here` for one project | `on` |
 | `--whisper` | Quick preset: 15% volume (headphones / late night) | — |
 | `--quiet` | Quick preset: 25% volume (focus / open office) | — |
 | `--loud` | Quick preset: 75% volume (hear from across the room) | — |
@@ -709,6 +742,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--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 |
 | `--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` | — |
 | `--events` | Stream agent state changes as JSON lines, starting with the current state, until stopped | — |
 | `--stop` | Stop the background player, then exit | — |
@@ -735,6 +769,7 @@ export VIBE_CHIME_VOLUME=70     # Crisp completion chime at 70%
 export VIBE_GRACE_MS=3000       # Wait 3s of thinking before any music
 export VIBE_SEED=7              # Same arrangement everywhere, ignoring the directory
 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_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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.15.0",
+  "version": "0.16.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

@@ -17,6 +17,7 @@ const {
   normalizeVolume,
   loadConfig,
   saveConfig,
+  musicEnabled,
   projectSettings,
   saveProjectConfig,
   wavDurationMs,
@@ -68,6 +69,7 @@ Procedural focus music while your AI coding tools think.
       --grace <ms>             Silence window before music starts, in ms (default: ${DEFAULT_GRACE_PERIOD_MS})
       --here                   With a saved setting: this directory only, not everywhere
       --seed <n>               Force a specific arrangement (default: derived from the project directory)
+      --music <on|off>         off = signals only: chimes, banners and events, no music (a saved setting)
       --whisper                Preset: 15% volume (late night / headphones)
       --quiet                  Preset: 25% volume (focus / open office)
       --loud                   Preset: 75% volume (hear from across the room)
@@ -79,6 +81,7 @@ Procedural focus music while your AI coding tools think.
       --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes or needs you (off 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
+      --statusline             Print that as one plain line for tmux or a prompt; prints nothing when idle
       --events                 Stream agent state changes as JSON lines, until stopped
       --doctor                 Check the setup; each problem comes with its fix (exit 1 if any)
       --stop                   Stop the background player, then exit
@@ -110,6 +113,7 @@ Procedural focus music while your AI coding tools think.
   VIBE_VOLUME=<5-100>          Override the saved volume for this shell
   VIBE_CHIME_VOLUME=<5-100>    Override the saved chime volume for this shell
   VIBE_GRACE_MS=<ms>           Override the saved grace window, in ms
+  VIBE_MUSIC=<on|off>          Override the saved music setting 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
@@ -136,6 +140,7 @@ const VALUE_FLAGS = new Set([
   "-v", "--volume",
   "-cv", "--chime-volume",
   "--grace",
+  "--music",
   "--seed",
   "--tools",
   "--event"
@@ -155,6 +160,7 @@ function parseArgs(argv) {
   const here = projectSettings(saved);
   const setting = (key) => (here[key] !== undefined ? here[key] : saved[key]);
 
+  let music = musicEnabled(process.env, saved);
   let genre = (process.env.VIBE_GENRE || setting("genre") || "lofi").toLowerCase();
 
   let volume = normalizeVolume(process.env.VIBE_VOLUME, normalizeVolume(setting("volume"), 0.40));
@@ -178,6 +184,7 @@ function parseArgs(argv) {
   let clearCacheFlag = false;
   let statusFlag = false;
   let stateFlag = false;
+  let statuslineFlag = false;
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
@@ -295,6 +302,24 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--music") {
+      const value = args[i + 1].toLowerCase();
+      if (value !== "on" && value !== "off") {
+        console.error(`\x1b[31m[vibeaudio] --music takes on or off, not '${args[i + 1]}'.\x1b[0m`);
+        process.exit(1);
+      }
+      music = value === "on";
+      typed.music = music;
+      i += 2;
+      continue;
+    }
+
+    if (arg === "--statusline") {
+      statuslineFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--state" || arg === "--events") {
       if (arg === "--state") stateFlag = true;
       else eventsFlag = true;
@@ -492,6 +517,8 @@ function parseArgs(argv) {
     clearCache: clearCacheFlag,
     status: statusFlag,
     state: stateFlag,
+    statusline: statuslineFlag,
+    music,
     events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
@@ -734,6 +761,7 @@ function printStatus() {
       : off("  default");
 
   console.log(`\x1b[1mSound\x1b[0m`);
+  console.log(`  music     ${musicEnabled() ? on("on") : "\x1b[33moff\x1b[0m"}${source("VIBE_MUSIC", "music")}${musicEnabled() ? "" : off("  signals only — vibe --music on")}`);
   console.log(`  genre     ${on(genreNow())}${source("VIBE_GENRE", "genre")}`);
   console.log(`  volume    ${on(`${Math.round(volumeNow() * 100)}%`)}${source("VIBE_VOLUME", "volume")}`);
   console.log(`            ${off("change either with: vibe --genre <name> --volume <n>")}`);
@@ -943,6 +971,7 @@ function doctorChecks() {
   if (mute !== null) add("warn", "Mute", `muted ${muteRemainingText(mute)}`, "vibe --unmute");
   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)");
 
   const pid = readDaemonPid(hooks.PID_FILE);
   if (pid === null) add("ok", "Background player", "not running");
@@ -1178,6 +1207,7 @@ function saveDefaults(typed, hereOnly = false) {
   if (typed.volume !== undefined) patch.volume = Math.round(typed.volume * 100);
   if (typed.chimeVolume !== undefined) patch.chimeVolume = Math.round(typed.chimeVolume * 100);
   if (typed.grace !== undefined) patch.grace = typed.grace;
+  if (typed.music !== undefined) patch.music = typed.music;
 
   const { CONFIG_FILE } = require("./player");
   if (hereOnly) saveProjectConfig(patch);
@@ -1187,7 +1217,8 @@ function saveDefaults(typed, hereOnly = false) {
     genre: (v) => `genre ${v}`,
     volume: (v) => `volume ${v}%`,
     chimeVolume: (v) => `chime volume ${v}%`,
-    grace: (v) => `grace ${v}ms`
+    grace: (v) => `grace ${v}ms`,
+    music: (v) => `music ${v ? "on" : "off"}`
   };
   const changed = Object.keys(patch).map((k) => label[k](patch[k])).join(", ");
   const where = hereOnly ? ` for ${process.cwd()}` : "";
@@ -1201,6 +1232,12 @@ function saveDefaults(typed, hereOnly = false) {
   if (playing && patch.genre && playing.genre && playing.genre !== patch.genre) {
     console.log(`  \x1b[90m${playing.genre} is still playing — vibe --stop cuts it short.\x1b[0m`);
   }
+  if (playing && patch.music === false) {
+    console.log(`  \x1b[90m${playing.genre || "The music"} is still playing — vibe --stop cuts it short.\x1b[0m`);
+  }
+  if (patch.music === false) {
+    console.log(`  \x1b[90mSignals only: chimes, banners, --events and --report work as before.\x1b[0m`);
+  }
   if (playing && playing.follows && patch.volume !== undefined) {
     console.log(`  \x1b[90mThe music playing now follows the new volume within a second.\x1b[0m`);
   }
@@ -1335,7 +1372,7 @@ function renderToFile(target, genre) {
   console.log(`  \x1b[90mAnother project's sound: run it there, or vibe --seed <n> --render.\x1b[0m\n`);
 }
 
-function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
+function runHookAction(action, { music = true, genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
   if (plugin && action.startsWith("hook-")) {
@@ -1361,7 +1398,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       // The payload names the session (so SessionEnd can tell this session's
       // music from another's) and the transcript (so an interrupt, which
       // fires no hook, can still stop it).
-      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
+      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { music, reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
       return;
 
     case "hook-stop":
@@ -1388,7 +1425,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       return;
 
     case "hook-resume":
-      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive, follow: typed.volume === undefined }));
+      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { music, reactive, follow: typed.volume === undefined, chimeVolume, noChime }));
       return;
 
     case "hook-end":
@@ -1455,10 +1492,10 @@ function windowsCommandNeedsShell(command) {
   return !/[\\/]/.test(command);
 }
 
-function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false) {
+function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false, music = true) {
   const player = new AudioPlayer();
   const hookDriven = hooksAlreadyCover(cmdArgs);
-  const hud = !noHud && !hookDriven ? new TerminalHud(genre) : null;
+  const hud = !noHud && !hookDriven && music ? new TerminalHud(genre) : null;
   const startTime = Date.now();
   let musicStarted = false;
   let finished = false;
@@ -1486,8 +1523,8 @@ function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRA
 
   // Grace window before triggering audio (silences fast commands)
   const graceTimer = hookDriven ? null : setTimeout(() => {
-    musicStarted = true;
-    player.start(genre, volume);
+    musicStarted = true; // Set with music off too: the chime marks the end of a run that outlasted the grace window.
+    if (music) player.start(genre, volume);
     if (hud) hud.start();
   }, grace);
 
@@ -1566,6 +1603,8 @@ async function run() {
     clearCache: shouldClear,
     status: showStatus,
     state: showState,
+    statusline: showStatusline,
+    music,
     events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
@@ -1596,7 +1635,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent, tools, dryRun, typed });
+      return runHookAction(hookAction, { music, genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent, tools, dryRun, typed });
     } catch (e) {
       // Settings problems are the user's to fix — report them, don't stack-trace.
       console.error(`\x1b[31m[vibeaudio] ${e.message}\x1b[0m`);
@@ -1667,6 +1706,14 @@ async function run() {
     return;
   }
 
+  // Idle prints nothing, not even a newline, so a prompt segment disappears.
+  if (showStatusline) {
+    const hooks = require("./hooks");
+    const line = hooks.formatStatusline(hooks.agentState());
+    if (line) console.log(line);
+    return;
+  }
+
   if (followEvents) {
     process.stdout.on("error", () => process.exit(0)); // `vibe --events | head` closing the pipe is not an error.
     require("./hooks").followEvents();
@@ -1736,10 +1783,10 @@ async function run() {
       }
     }
 
-    return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud);
+    return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud, music);
   }
 
-  executeCommand(cmdArgs, genre, volume, chimeVolume, grace, noChime, noHud);
+  executeCommand(cmdArgs, genre, volume, chimeVolume, grace, noChime, noHud, music);
 }
 
 module.exports = {

package/src/hooks.js

@@ -755,6 +755,20 @@ function agentState(sessions = listSessions()) {
   return { v: 1, status, sessions: list };
 }
 
+/**
+ * `vibe --statusline`: the state as one plain line for a tmux segment or a
+ * shell prompt, and nothing at all when idle so the segment disappears. The
+ * most urgent status, with a count when more than one session is in it; a
+ * waiting session names its project, since that is the one you have to go to.
+ * Plain text because tmux and Starship style it themselves.
+ */
+function formatStatusline({ status, sessions }) {
+  if (status === "idle") return "";
+  const active = sessions.filter((s) => s.state === status);
+  const project = status === "waiting" && active[0].project ? `: ${projectName(active[0].project)}` : "";
+  return `${status}${project}${active.length > 1 ? ` ×${active.length}` : ""}`;
+}
+
 const EVENTS_MAX_BYTES = 256 * 1024;
 
 /**
@@ -973,7 +987,7 @@ function spawnDaemon(genre, volume, reactive, follow = false) {
  * always did, so a genre change lands on the next prompt. With one working the
  * music carries on: restarting it would cut every other session's stream.
  */
-function hookStart(genre, volume, { reactive = false, turn = null, follow = false } = {}) {
+function hookStart(genre, volume, { reactive = false, turn = null, follow = false, music = true } = {}) {
   if (turn && turn.blocked) return null; // Rejected before it began: nothing to play for.
   if (turn && turn.continues) return null; // A later model call in a turn already playing.
   const id = sessionId(turn && turn.session);
@@ -985,6 +999,10 @@ function hookStart(genre, volume, { reactive = false, turn = null, follow = fals
 
   stopDaemon({ keepSessions: true });
   fs.rmSync(INTENSITY_FILE, { force: true }); // Don't inherit the last prompt's activity
+  // Signals only: the session is tracked (chimes, events and the report read
+  // it) but there is no music to start. Stopping first means a switch to off
+  // lands on the next prompt rather than playing until the turn ends.
+  if (!music) return null;
   return spawnDaemon(genre, volume, reactive, follow);
 }
 
@@ -1050,9 +1068,12 @@ function notifyEnabled(env = process.env, config = loadConfig()) {
 }
 
 /** The project a hook fired in: the payload's (see payloadProject), else ours. */
+function projectName(dir) {
+  return path.basename(String(dir).replace(/[\\/]+$/, "")) || "a session";
+}
+
 function sessionLabel(payload, cwd = process.cwd()) {
-  const dir = payloadProject(payload) || cwd;
-  return path.basename(dir.replace(/[\\/]+$/, "")) || "a session";
+  return projectName(payloadProject(payload) || cwd);
 }
 
 /**
@@ -1183,7 +1204,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * one needing approval, can resume early - after the chime already did its
  * job. Match on tool_input as well if that ever shows up in practice.
  */
-function hookResume(raw, genre, volume, { reactive = false, follow = false } = {}) {
+function hookResume(raw, genre, volume, { reactive = false, follow = false, music = true, chimeVolume = null, noChime = false } = {}) {
   const payload = parsePayload(raw);
   const id = sessionId(payloadSession(payload));
   const session = readSession(id);
@@ -1197,7 +1218,13 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false } = {
   const recent = [...(session.recent || []), failed ? 1 : 0].slice(-STUCK_WINDOW);
   const next = { ...session, recent };
   const crossing = isStuck(next) === isStuck(session) ? null : isStuck(next) ? "stuck" : "recovered";
-  if (crossing === "stuck") notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+  if (crossing === "stuck") {
+    notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+    // With music on the daemon adds the heartbeat; with it off there is no
+    // 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 });
+  }
 
   // An empty key is a wait that named nothing (a Notification): the next tool
   // to finish is the first sign of work carrying on.
@@ -1212,7 +1239,7 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false } = {
   writeSession(id, { ...next, waiting: null, waitStart: null, blockedMs });
   emitEvent("resumed", id, session.project);
   if (crossing) emitEvent(crossing, id, session.project);
-  if (!daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
+  if (music && !daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
   return true;
 }
 
@@ -1565,6 +1592,7 @@ module.exports = {
   isStuck,
   STUCK_WINDOW,
   agentState,
+  formatStatusline,
   followEvents,
   EVENTS_FILE,
   hookEnd,

package/src/mcp.js

@@ -6,7 +6,7 @@
  */
 
 const readline = require("readline");
-const { AudioPlayer, AVAILABLE_GENRES, normalizeVolume, playbackDisabled, isKnownGenre, loadConfig } = require("./player");
+const { AudioPlayer, AVAILABLE_GENRES, normalizeVolume, playbackDisabled, musicEnabled, isKnownGenre, loadConfig } = require("./player");
 const pkg = require("../package.json");
 
 // A desktop client that crashes never sends vibe_stop, so playback needs its
@@ -148,6 +148,15 @@ function handleMessage(player, msg) {
       const volume = normalizeVolume(args.volume,
         normalizeVolume(process.env.VIBE_VOLUME, normalizeVolume(saved.volume, 0.4)));
 
+      // A deliberate setting, like a mute: report it as one, and start nothing.
+      if (!musicEnabled()) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: { content: [{ type: "text", text: "The user has turned VibeAudio's music off (signals only), so nothing will play. This is deliberate and not an error — do not try again or suggest fixes; they will turn it back on when they want music." }] }
+        };
+      }
+
       const started = player.start(genre, volume, { maxDurationMs: MAX_PLAYBACK_MS });
       // start() returns false for three unrelated reasons, and the model
       // relays whatever we say here to the user. Reporting a deliberate mute
@@ -204,6 +213,7 @@ function handleMessage(player, msg) {
                 // Without this, "isPlaying: false" while muted reads as a bug
                 // worth investigating rather than a choice the user made.
                 muted: playbackDisabled(),
+                musicOff: !musicEnabled(),
                 genre: player.genre,
                 currentTier: player.currentTier,
                 uptimeMs: player.isPlaying ? Date.now() - player.startTime : 0

package/src/player.js

@@ -18,7 +18,7 @@ const { generateRainLoop } = require("./synth/rain");
 const { generateOceanLoop } = require("./synth/ocean");
 const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
-const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
+const { generateSuccessChime, generateFailureChime, generateAttentionChime, generateStuckChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
 const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
@@ -430,6 +430,19 @@ function playbackDisabled() {
   return muteState() !== null;
 }
 
+/**
+ * Whether music plays at all, as opposed to `playbackDisabled()`, which
+ * silences everything including the chimes. Some people want only the
+ * signals (done, failed, needs you), so this is a setting of its own rather
+ * than a genre: `genre` stays what it was for when music comes back on.
+ * Env beats this directory's saved value beats the global one; a flag is
+ * resolved by parseArgs() and handed to whoever acts on it.
+ */
+function musicEnabled(env = process.env, config = loadConfig()) {
+  const raw = env.VIBE_MUSIC ?? projectSettings(config).music ?? config.music ?? "on";
+  return !["off", "0", "false", "no"].includes(String(raw).trim().toLowerCase());
+}
+
 /**
  * `minutes` of 0 means indefinite, which the user has to ask for explicitly.
  */
@@ -652,7 +665,8 @@ function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0,
 const CHIMES = {
   success: generateSuccessChime,
   failure: generateFailureChime,
-  attention: generateAttentionChime
+  attention: generateAttentionChime,
+  stuck: generateStuckChime
 };
 
 /**
@@ -965,6 +979,7 @@ module.exports = {
   bakedGain,
   applyGain,
   playbackDisabled,
+  musicEnabled,
   resolveGenre,
   isKnownGenre,
   normalizeVolume,

package/src/synth/chime.js

@@ -143,11 +143,32 @@ function generateAttentionChime(durationSec = 1.3) {
   return createWavBuffer({ left, right, sampleRate: SAMPLE_RATE });
 }
 
+/**
+ * "Looks stuck", for someone with the music off, who has no loop for the
+ * heartbeat to sit under. It is that same heartbeat on its own - two lub-dubs
+ * on A, a resting pulse - so it means what the layer means: not an outcome and
+ * not a question, just something that has not changed for a while. Quiet, and
+ * low enough to read as a pulse rather than a tone.
+ */
+function generateStuckChime(durationSec = 1.8) {
+  const { thump, pulseFreq, BEAT_S, DUB_DELAY_S } = require("./tension");
+  const f = pulseFreq("A minor");
+  const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
+  const out = new Float64Array(totalSamples);
+  for (let i = 0; i < totalSamples; i++) {
+    const t = i / SAMPLE_RATE;
+    const local = t % BEAT_S;
+    out[i] = 0.3 * (thump(local, f) + 0.7 * thump(local - DUB_DELAY_S, f));
+  }
+  return createWavBuffer({ left: out, right: out, sampleRate: SAMPLE_RATE });
+}
+
 module.exports = {
   DEFAULT_CHIME_KEY,
   SUCCESS_CHIME_NOTES,
   generateChime: generateSuccessChime,
   generateSuccessChime,
   generateFailureChime,
-  generateAttentionChime
+  generateAttentionChime,
+  generateStuckChime
 };

package/src/synth/tension.js

@@ -64,4 +64,4 @@ function addTension(wav, key) {
   return out;
 }
 
-module.exports = { addTension, pulseFreq };
+module.exports = { addTension, pulseFreq, thump, BEAT_S, DUB_DELAY_S };