vibeaudio 0.25.2 → 0.26.0

package/README.md

@@ -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`
@@ -878,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 | — |

package/package.json

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

@@ -99,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
@@ -238,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;
@@ -422,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;
@@ -649,6 +657,7 @@ function parseArgs(argv) {
     status: statusFlag,
     state: stateFlag,
     statusline: statuslineFlag,
+    why: whyFlag,
     music,
     events: eventsFlag,
     doctor: doctorFlag,
@@ -1837,6 +1846,7 @@ async function run() {
     status: showStatus,
     state: showState,
     statusline: showStatusline,
+    why: showWhy,
     music,
     events: followEvents,
     doctor: showDoctor,
@@ -2011,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",