vibeaudio 0.25.1 → 0.26.0

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.
 
@@ -300,7 +300,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | :--- | :--- |
 | **Five agents tell you when they're waiting on you** | When a permission dialog opens the music stops rather than sounding busy while the agent is stuck on you, and it resumes once the thing you answered has run. Claude Code covers the terminal, desktop app and IDEs alike, plus MCP servers asking for input. Copilot CLI's own `PermissionRequest` fires before *every* permission check — dialog or not — so VibeAudio listens for its permission-prompt notification instead. Cursor and Grok have no such event that's been verified, so they keep playing through a prompt. |
 | **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. A prompt that another hook blocks (a token-saving proxy, say) never reaches `Stop` either, so the same watcher ends the music on Claude Code's "prompt blocked" entry — or never starts it, when the blocker was quicker than we were. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
-| **Codex asks you to trust the hook once** | Codex keeps a per-hook trust hash in `~/.codex/config.toml` and won't run a hook it hasn't been told to trust, so the install isn't live until you approve each one the first time it fires. |
+| **Codex asks you to trust the hook once** | Codex keeps a per-hook trust hash in `~/.codex/config.toml` and won't run a hook it hasn't been told to trust, so the install isn't live until you approve each one. The CLI asks the first time each fires; the Codex desktop app shows **Review hooks** in the composer, where **Allow all** approves them in one go. Both write the same records, so approving in one covers the other. |
 | **Cursor and Antigravity say how a turn ended** | Cursor's stop event reports whether the turn completed, aborted or errored, and Antigravity's gives a termination reason, so an error plays the failure chime. Claude Code and Qwen Code send a separate `StopFailure` for an API error. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
 | <a id="antigravity-hooks"></a>**Antigravity never gets a pre-tool hook** | Its pre-tool hook has to approve or deny every tool call — one that answers nothing blocks the tool — so VibeAudio installs none, and `--reactive` does nothing there. It has no prompt event either: the start event fires before every model call, and VibeAudio starts the music on the first one of each prompt only. Its hooks live in `~/.gemini/config/hooks.json` under a name of their own, so your other named hooks there are never touched. Verified with the `agy` CLI; the desktop app reads the same file by Antigravity's own docs but hasn't been checked live. |
 | **Upgraded, and a new feature isn't there?** | Hooks are written into your agent's config once, at install time, and an upgrade doesn't touch them. When a new version listens for more events (0.13.1 added Codex's `Interrupt` and `SessionEnd`), `vibe --doctor` and `vibe --status` name what's missing, and `vibe --install-hooks` adds it. |
@@ -334,6 +334,8 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-vs-code-via-mcp).)
 
+> **So is the Codex desktop app** (the Codex side of the ChatGPT app): it runs the same Codex engine on the same `~/.codex/hooks.json`, so `--install-hooks` covers it with nothing extra. Approve the hooks once from its **Review hooks** prompt. Its stop button ends the music silently, as Codex's `Interrupt` does in the CLI.
+
 > **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`
@@ -429,6 +431,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
@@ -864,7 +872,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 |
@@ -872,6 +880,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--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 | — |
+| `--why` | Why the music is playing or silent, as one plain line (the first line of `--status`) | — |
 | `--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 | — |
 | `--dashboard` | Serve a read-only live view of every agent on this machine at `http://127.0.0.1:4747`, and open it. `--port <n>` and `--no-open` adjust it | — |
@@ -935,6 +944,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.1",
+  "version": "0.26.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

@@ -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
@@ -95,6 +99,7 @@ Procedural focus music while your AI coding tools think.
       --port <n>               With --dashboard: the port (default ${require("./dashboard").DEFAULT_PORT}, else a free one)
       --no-open                With --dashboard: do not open the browser
       --statusline             Print that as one plain line for tmux or a prompt; prints nothing when idle
+      --why                    One plain line: why the music is playing or silent (the first line of --status)
       --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
@@ -234,6 +239,7 @@ function parseArgs(argv) {
   let statusFlag = false;
   let stateFlag = false;
   let statuslineFlag = false;
+  let whyFlag = false;
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
@@ -418,6 +424,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--why") {
+      whyFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--state" || arg === "--events") {
       if (arg === "--state") stateFlag = true;
       else eventsFlag = true;
@@ -645,6 +657,7 @@ function parseArgs(argv) {
     status: statusFlag,
     state: stateFlag,
     statusline: statuslineFlag,
+    why: whyFlag,
     music,
     events: eventsFlag,
     doctor: doctorFlag,
@@ -869,21 +882,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.
@@ -1817,6 +1846,7 @@ async function run() {
     status: showStatus,
     state: showState,
     statusline: showStatusline,
+    why: showWhy,
     music,
     events: followEvents,
     doctor: showDoctor,
@@ -1991,6 +2021,13 @@ async function run() {
     return;
   }
 
+  // --status's first line without the rest, plain: for the mod's pane and band (#60), a prompt segment, a script.
+  if (showWhy) {
+    const hooks = require("./hooks");
+    console.log(hooks.explainMusic(musicFacts()).text);
+    return;
+  }
+
   if (dashboard) {
     const { startDashboard } = require("./dashboard");
     let server;

package/src/hooks.js

@@ -266,7 +266,7 @@ const TARGETS = {
     seed: () => ({}),
     // Codex records a trusted_hash per hook in config.toml and asks before
     // running one it has not seen, so the install is not live until approved.
-    note: "Codex asks you to trust each new hook the first time it fires — approve each one once."
+    note: "Codex asks you to trust each new hook once — in the desktop app via Review hooks in the composer (Allow all), in the CLI the first time each fires."
   },
   cursor: {
     name: "Cursor",
@@ -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,