vibeaudio 0.25.0 → 0.25.2

package/README.md

@@ -160,7 +160,7 @@ vibe npm test
 vibe claude -p "explain this repo"
 ```
 
-**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found. If something seems broken, `vibe --doctor` checks it and prints the fix for each problem.
+**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found. Its first line says why the music is silent or playing right now (`silent: muted for 42 more min (vibe --unmute)`, `playing: lofi @ 40%, 2 sessions working (api, web)`). If something seems broken, `vibe --doctor` checks it and prints the fix for each problem.
 
 > **Which one you want:** the wrapper plays music for as long as the wrapped process lives. That's exactly right for a command that exits when its work is done — and wrong for an interactive REPL like `claude`, where the process stays alive while you read and type, so the music never stops. Hooks know when the agent is actually thinking; the wrapper can only time the process.
 
@@ -429,6 +429,12 @@ The optional [`/vibeaudio` mod](#vibeaudio-instant-controls-and-a-pane-claude-co
 
 `/vibe` is a prompt, so Claude has to read it, run a command and answer: it costs a turn and a few tokens, and it waits for the current turn to end. The optional **VibeAudio mod** runs inside Claude Code instead, so `/vibeaudio mute` takes effect at once, even while Claude is working, and costs no tokens.
 
+<p align="center">
+  <a href="https://kiril6.github.io/vibeaudio/#band-video"><img src="docs/video/band-poster.jpg" alt="The VibeAudio band above the Claude Code prompt" width="49%"></a>
+  <a href="https://kiril6.github.io/vibeaudio/#band-video"><img src="docs/video/pane.jpg" alt="The VibeAudio pane: now playing, sound, alerts and share" width="49%"></a>
+  <br><sub>▶ <a href="https://kiril6.github.io/vibeaudio/#band-video">Watch the 43-second demo</a> of the band and the pane (frames from the demo video, with sound on the site).</sub>
+</p>
+
 ```text
 claude plugin marketplace add kiril6/vibeaudio
 claude plugin install vibeaudio-mod@vibeaudio
@@ -445,14 +451,14 @@ To update later, run `claude plugin marketplace update vibeaudio` and then `clau
 /vibeaudio genre zen here   genre, volume and music also take "here": save for this project only
 /vibeaudio card          make your week card; the pane shows it in terminals that draw images
 /vibeaudio band on       an always-visible logo band above the prompt (off by default; band off removes it)
-/vibeaudio usage on      add context fill and plan limits (ctx ██░░░ 42%  5h █░░░░ 31%, green, amber from 60%, red from 80%) to the band (off by default; usage off removes it)
+/vibeaudio usage on      add context fill and plan limits (ctx 42%  5h 31%) to the band (off by default; usage off removes it)
 /vibeaudio doctor        the setup check in a pane, each problem with its fix (vibe --doctor)
 /vibeaudio help          every command on one line, and the "here" option
 ```
 
-The pane is four cards under a logo header with a status pill (Playing, Ready, Muted or Music off): Now playing (mute for 15 minutes or an hour, stop the music, send a test signal), Sound (genre, volume, **Preview** plays one loop of the chosen genre, and where to save), Alerts (speech, banners, `vibe --announce`) and Share, which holds your last 7 days as a small chart and the week card buttons. Its colours come from the site and adapt to your Claude Code theme, light or dark. While you are muted, a line above the prompt says how many minutes are left, so a forgotten mute does not look like a broken tool. Nothing else is shown unless you turn the strip on.
+The pane is four cards under a logo header with a status pill (Playing, Ready, Muted or Music off): Now playing (mute for 15 minutes or an hour, stop the music, send a test signal), Sound (genre, volume, **Preview** plays one loop of the chosen genre, and where to save), Alerts (speech, banners, `vibe --announce`) and Share, which holds your last 7 days as a small chart and the week card buttons. Its colours come from the site and adapt to your Claude Code theme, light or dark. While you are muted, a line above the prompt says how many minutes are left, so a forgotten mute does not look like a broken tool. Nothing else is shown unless you turn the band on.
 
-The optional **band** (`/vibeaudio band on`, remembered across sessions) puts the VibeAudio logo above the prompt, three level bars that move while music is playing (an SVG on the Desktop app, text bars in the terminal). Next to it: the genre and volume, your last 7 days as the week card counts them (turns and time waited, read from `~/.vibeaudio/history.jsonl`), and what your other agents are doing (`api waiting, web working`, in yellow when one needs you). The buttons are icons to save room: 🔇/🔊 mute and unmute, 🎵 music on or off, 🎼 the next genre, − and + for volume, 📊 the week card (then 🖼 to open it) and ⚙ for the controls pane. In a short window it shrinks to one line. It runs `vibe --state` every 5 seconds and redraws the text bars twice a second only in the terminal, while it is on and music is playing; on the Desktop app the SVG animates itself, so only the level bars inside the headphones move. Tab to it with Ctrl+X then Tab. With `/vibeaudio usage on` it also shows how full the context window is and, on a Claude plan, your 5-hour and 7-day limits, turning the warning colour at 80%; it reads the same figures Claude Code's status line has, and nothing else. While Claude works, the spinner also says what is playing (`· ♪ jazz…`, or `· ♪ muted`).
+The optional **band** (`/vibeaudio band on`, remembered across sessions) puts the VibeAudio logo above the prompt, three level bars that move while music is playing (an SVG on the Desktop app, text bars in the terminal). Next to it: the genre and volume, your last 7 days as the week card counts them (turns and time waited, read from `~/.vibeaudio/history.jsonl`). The bars also move while another agent on the machine is working. The buttons are compact icons that show the current state: 🔊/🔇 sound on or muted (press to flip it), ♪ on/off for music, ♫ with the current genre (press for the next one), − and + for volume, ▤ week for the week card (then ↗ to open it) and ⚙ for the controls pane. In a short window it shrinks to one line. It runs `vibe --state` every 5 seconds and redraws the text bars twice a second only in the terminal, while it is on and music is playing; on the Desktop app the SVG animates itself, so only the level bars inside the headphones move. Tab to it with Ctrl+X then Tab. With `/vibeaudio usage on` it also shows how full the context window is and, on a Claude plan, your 5-hour and 7-day limits, turning the warning colour at 80%; it reads the same figures Claude Code's status line has, and nothing else. While Claude works, the spinner also says what is playing (`· ♪ jazz…`, or `· ♪ muted`).
 
 - **Per project.** The pane's **Saving** button switches genre, volume and music between everywhere and this project, and the pane notes when this folder has its own settings (`vibe --genre zen --here`, found from a subfolder the way the CLI does). There is no way to remove a project's settings yet, in the mod or the CLI.
 - **It changes nothing itself.** Every action runs the `vibe` command with a fixed argument list (no shell), so settings stay in `~/.vibeaudio/config.json` and the pane cannot disagree with the CLI. The one thing it keeps for itself is whether the band is on, in Claude Code's own store for the mod. It needs `vibe` on your `PATH` (`npm i -g vibeaudio`) and **Claude Code 2.1.287 or later** (Desktop app 2.1.286). It draws in the terminal and the Desktop app; in the VS Code panel and `claude -p` the same commands answer in text. It makes no network request.
@@ -864,7 +870,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--no-hud` | Disable terminal window/tab title animation | `false` |
 | `--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`) | `vibeaudio-<genre>.wav` |
-| `--status` | Show what's installed, running and detected, then exit | — |
+| `--status` | Say why the music is silent or playing, then show what's installed, running and detected, and 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 |
@@ -935,6 +941,8 @@ The expiry is deliberate too. A call is a bounded thing; a mute you forget about
 
 ## 🔧 Troubleshooting
 
+**Start with `vibe --status`.** Its first line answers "why is it silent?" or "why is it still playing?" in one sentence, with the command that changes it: a mute and how long it has left, `VIBE_DISABLE` in your shell, no audio player, music turned off (globally, for this project, or by `VIBE_MUSIC`), a session waiting on you, or simply no agent working right now.
+
 **No sound at all**
 Check that a player exists for your platform (see [Requirements](#-requirements)). VibeAudio prints a notice to stderr when it can't find one. On Linux: `sudo apt install pulseaudio-utils` (or `ffmpeg` / `alsa-utils`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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

@@ -41,6 +41,9 @@ const HOOK_ACTIONS = [
 ];
 
 function printHelp() {
+  // Both callers process.exit() next. On macOS a piped stdout is async, so Node 18/20
+  // dropped everything past the 8 KB pipe buffer (CI on #77). Blocking writes flush first.
+  process.stdout._handle?.setBlocking?.(true);
   console.log(`
 \x1b[1m\x1b[36mVibeAudio\x1b[0m v${pkg.version}
 Procedural focus music while your AI coding tools think.
@@ -80,7 +83,8 @@ Procedural focus music while your AI coding tools think.
       --no-hud                 Disable terminal window/tab title animation
       --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
+      --status                 Say why the music is silent or playing, then show what is
+                               installed, running and detected, and exit
       --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
@@ -869,21 +873,37 @@ function uninstallHookTargets() {
  * do". Every line is read from live state rather than assumed, because the
  * usual cause of confusion is a mismatch between config and what is running.
  */
+// What hooks.explainMusic() needs, read once: the same sources the sections of
+// --status read, so the one-line answer cannot disagree with them.
+function musicFacts() {
+  const hooks = require("./hooks");
+  const { muteState, playbackDisabled, detectPlayer: detect } = require("./player");
+  const mute = muteState();
+  const daemon = hooks.daemonPlaying();
+  return {
+    disabledByEnv: mute === null && playbackDisabled(),
+    mute: mute === null ? null : mute.until ? Math.max(1, Math.round((mute.until - Date.now()) / 60000)) : Infinity,
+    backend: Boolean(detect()),
+    daemon,
+    genre: genreNow(),
+    volume: daemon ? (daemon.follows ? Math.round(volumeNow() * 100) : daemon.volume) : null,
+    music: musicEnabled(),
+    musicSource: process.env.VIBE_MUSIC ? "env" : projectSettings(loadConfig()).music !== undefined ? "project" : "",
+    sessions: hooks.agentState().sessions
+  };
+}
+
 function printStatus() {
   const hooks = require("./hooks");
-  const { playbackDisabled, detectPlayer: detect, CACHE_ROOT } = require("./player");
+  const { detectPlayer: detect, CACHE_ROOT } = require("./player");
   const on = (s) => `\x1b[32m${s}\x1b[0m`;
   const off = (s) => `\x1b[90m${s}\x1b[0m`;
 
   console.log(`\n\x1b[1m\x1b[36mVibeAudio\x1b[0m v${pkg.version}\n`);
 
-  const { muteState, muteRemainingText } = require("./player");
-  const mute = muteState();
-  if (mute !== null) {
-    console.log(`\x1b[33m🔇 Muted ${muteRemainingText(mute)}\x1b[0m \x1b[90m(since ${mute.since})\x1b[0m\n`);
-  } else if (playbackDisabled()) {
-    console.log(`\x1b[33m⏸ Muted by VIBE_DISABLE=${process.env.VIBE_DISABLE}\x1b[0m — automatic playback is off (--preview still works).\n`);
-  }
+  // The answer first (#76): everything below is the detail behind it.
+  const now = hooks.explainMusic(musicFacts());
+  console.log(`\x1b[1mNow\x1b[0m  ${now.playing ? on(now.text) : `\x1b[33m${now.text}\x1b[0m`}\n`);
 
   // What will actually play, and which of the three possible sources decided
   // it - the usual confusion is a saved default quietly beaten by an export.

package/src/hooks.js

@@ -805,6 +805,50 @@ function formatStatusline({ status, sessions }) {
   return `${status}${project}${active.length > 1 ? ` ×${active.length}` : ""}`;
 }
 
+/**
+ * "Why is it silent?" / "why is it still playing?" as one line, the first of
+ * --status (#76). Pure over what --status gathers (`musicFacts()` in cli.js),
+ * so the order is the test: what silences everything (VIBE_DISABLE, a mute)
+ * outranks what silences only the music, and a running player outranks every
+ * reason it might not be running. Each silent line names the command that
+ * changes it. `mute` is the minutes left, Infinity for an open-ended mute,
+ * null when not muted; `musicSource` is "env", "project" or "" (saved or default).
+ */
+function explainMusic({ disabledByEnv, mute, backend, daemon, genre, volume, music, musicSource, sessions }) {
+  const names = (list) => {
+    const all = [...new Set(list.map((s) => (s.project ? projectName(s.project) : null)).filter(Boolean))];
+    return all.length > 3 ? `${all.slice(0, 3).join(", ")} +${all.length - 3}` : all.join(", ");
+  };
+  const counted = (list, word) => {
+    const n = names(list);
+    return `${list.length} session${list.length === 1 ? "" : "s"} ${word}${n ? ` (${n})` : ""}`;
+  };
+  const silent = (text) => ({ playing: false, text: `silent: ${text}` });
+  const working = sessions.filter((s) => s.state !== "waiting");
+  const waiting = sessions.filter((s) => s.state === "waiting");
+
+  if (disabledByEnv) return silent("VIBE_DISABLE is set in this shell (unset it to hear music)");
+  if (mute != null) return silent(`muted ${mute === Infinity ? "until you unmute" : `for ${mute} more min`} (vibe --unmute)`);
+  if (!backend) return silent("no audio player found on this machine (vibe --doctor)");
+  if (daemon) {
+    const stuck = sessions.filter((s) => s.state === "stuck");
+    const level = volume === null ? "" : ` @ ${volume}%`;
+    return {
+      playing: true,
+      text: `playing: ${daemon.genre || genre}${level}, ${working.length ? counted(working, "working") : "finishing a turn"}` +
+        `${stuck.length ? `; heartbeat on, ${names(stuck) || "a session"} keeps failing` : ""}`
+    };
+  }
+  if (waiting.length && !working.length) return silent(`${counted(waiting, "waiting on you")}; music resumes when you answer`);
+  if (!music) {
+    // The fix has to beat whatever turned it off: a saved global does not outrank an export or --here.
+    const [where, fix] = { env: [" by VIBE_MUSIC in this shell", "unset VIBE_MUSIC"], project: [" for this project", "vibe --music on --here"] }[musicSource] || ["", "vibe --music on"];
+    return silent(`music is off${where}; chimes still play (${fix})`);
+  }
+  if (working.length) return silent(`${counted(working, "working")} but the player is not running (vibe --doctor)`);
+  return silent("no agent is working; music starts with your next prompt");
+}
+
 const EVENTS_MAX_BYTES = 256 * 1024;
 
 /**
@@ -1781,6 +1825,7 @@ module.exports = {
   STUCK_WINDOW,
   agentState,
   formatStatusline,
+  explainMusic,
   followEvents,
   EVENTS_FILE,
   hookEnd,