vibeaudio 0.13.1 → 0.14.1

package/README.md

@@ -12,7 +12,7 @@
 
 > **In a hurry?** `npm i -g vibeaudio`, then `vibe --install-hooks`. Your next prompt has music.
 >
-> **Claude Code only?** Skip npm: `claude plugin marketplace add kiril6/vibeaudio`, then `claude plugin install vibeaudio@vibeaudio` ([details](#as-a-claude-code-plugin)).
+> **Only Claude Code or Codex?** Skip npm. Inside a Claude Code session: `/plugin marketplace add kiril6/vibeaudio`, then `/plugin install vibeaudio@vibeaudio`. For Codex: `codex plugin marketplace add kiril6/vibeaudio`, then `codex plugin add vibeaudio@vibeaudio` ([details](#as-a-plugin-claude-code-and-codex)).
 
 ---
 
@@ -32,6 +32,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 **How it behaves:**
 
 * 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no `node-gyp`.
+* 🍃 **Light on battery.** Each loop is rendered once and cached. While music plays, your OS's own audio player does the work. With hooks, nothing of VibeAudio's keeps running between turns.
 * 🎼 **A different arrangement per project.** Your working directory seeds the progression, bass line and melody, so each repo has its own sound and keeps it.
 * 📈 **Escalating layers.** Tier 1 (0–15s) gentle intro → Tier 2 (15–45s) main groove → Tier 3 (45s+) deep focus. You can hear how deep into the task the agent is.
 * 🔁 **A phrase, not a loop.** Each piece is three bars that rotate through your project's own progressions, so a long turn moves through a ~21-second phrase instead of replaying one 7-second bar for half an hour.
@@ -324,20 +325,36 @@ 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.
 
-### As a Claude Code plugin
+### As a plugin (Claude Code and Codex)
 
-If Claude Code is the only agent you use, the plugin installs the same hooks with no npm step:
+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:
+
+```
+/plugin marketplace add kiril6/vibeaudio
+/plugin install vibeaudio@vibeaudio
+```
+
+Or the same from a terminal:
 
 ```bash
 claude plugin marketplace add kiril6/vibeaudio
 claude plugin install vibeaudio@vibeaudio
 ```
 
-It needs Node 18+ on your `PATH` (the hooks run `node`), and it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
+For Codex:
+
+```bash
+codex plugin marketplace add kiril6/vibeaudio
+codex plugin add vibeaudio@vibeaudio
+```
+
+Codex asks you to approve the plugin's hooks once, as it does for any hook. Update with `codex plugin marketplace upgrade vibeaudio`; remove with `codex plugin remove vibeaudio@vibeaudio`.
+
+The plugin needs Node 18+ on your `PATH` (the hooks run `node`). In Claude Code it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
 
 - **Settings are the same file.** `vibe --genre jazz` and the rest work as always, but the `vibe` command comes from `npm i -g vibeaudio`; the plugin alone puts nothing on your `PATH`. Use `/vibeaudio:vibe genre jazz` instead.
 - **Both at once is safe.** If `--install-hooks` has also been run, the plugin's hooks step aside and the installed ones play, so there's no double chime. Remove the installed hooks first if you want the plugin to own it.
-- **Claude Code only.** Codex, Cursor, Gemini and the others still use `vibe --install-hooks`.
+- **Claude Code and Codex.** Cursor, Gemini and the others still use `vibe --install-hooks`. Copilot CLI and Qwen Code can load the same plugin and it carries their events, but neither has been run with it yet.
 - **Not reactive.** `--reactive` is an `--install-hooks` option; the plugin doesn't carry it.
 
 ### `/vibe` inside Claude Code
@@ -466,7 +483,7 @@ Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiti
 {"v":1,"at":1791026130000,"event":"waiting","session":"…","project":"/work/api","tool":"Bash","status":"waiting"}
 ```
 
-Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended`. Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
 
 ```bash
 # tmux: show the state in the status bar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.13.1",
+  "version": "0.14.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",
@@ -10,7 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
-    "version": "node -e \"const f='.claude-plugin/plugin.json',j=require('./'+f);j.version=require('./package.json').version;require('fs').writeFileSync(f,JSON.stringify(j,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
+    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json",
     "postinstall": "node scripts/postinstall.js"
   },
   "publishConfig": {

package/src/cli.js

@@ -137,7 +137,8 @@ const VALUE_FLAGS = new Set([
   "-cv", "--chime-volume",
   "--grace",
   "--seed",
-  "--tools"
+  "--tools",
+  "--event"
 ]);
 
 function parseArgs(argv) {
@@ -189,6 +190,7 @@ function parseArgs(argv) {
   let reactive = false;
   let followVolume = false;
   let plugin = false;
+  let hookEvent = null;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -381,6 +383,14 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Internal, also the plugin's: which event this hook entry is for, so a
+    // hook can ignore events the agent running it does not use that way.
+    if (arg === "--event") {
+      hookEvent = args[i + 1] || null;
+      i += 2;
+      continue;
+    }
+
     if (arg === "--dry-run") {
       dryRun = true;
       i += 1;
@@ -494,6 +504,7 @@ function parseArgs(argv) {
     reactive,
     followVolume,
     plugin,
+    hookEvent,
     dryRun,
     tools,
     typed,
@@ -688,7 +699,7 @@ function uninstallHookTargets() {
   // `npm rm -g` right after this would take away the only thing that could
   // stop it. Done here rather than in uninstallHooks() so that function stays
   // a pure config edit for tests.
-  if (hooks.stopDaemon()) console.log(`  Stopped the background player that was still running.`);
+  if (hooks.stopDaemon({ reason: "uninstall" })) console.log(`  Stopped the background player that was still running.`);
 }
 
 /**
@@ -1324,13 +1335,23 @@ 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, tools, dryRun, typed = {} }) {
+function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
-  // The plugin's hooks and --install-hooks' hooks are the same events: with both
-  // present every prompt would restart the music and every turn chime twice.
-  // The installed ones win because they carry the user's --reactive choice.
-  if (plugin && action.startsWith("hook-") && hooks.userHooksInstalled()) return;
+  if (plugin && action.startsWith("hook-")) {
+    // One plugin, four agents (PLUGIN_AGENTS). Each check is against the
+    // agent actually running this hook, never Claude Code's by default.
+    const agent = hooks.pluginAgent();
+    // The plugin's hooks and --install-hooks' hooks are the same events: with
+    // both present every prompt would restart the music and every turn chime
+    // twice. The installed ones win because they carry the user's --reactive.
+    if (hooks.userHooksInstalled(null, agent)) return;
+    // The plugin's file carries every agent's events; this one may not use
+    // this event this way. Copilot fires PermissionRequest before every
+    // permission check, dialog or not, so taking it as a wait there would
+    // pause the music on every tool call.
+    if (hookEvent && !hooks.expectedEvents(agent).includes(hookEvent)) return;
+  }
 
   switch (action) {
     case "daemon":
@@ -1557,6 +1578,7 @@ async function run() {
     reactive,
     followVolume,
     plugin,
+    hookEvent,
     dryRun,
     tools,
     typed,
@@ -1574,7 +1596,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, tools, dryRun, typed });
+      return runHookAction(hookAction, { 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`);
@@ -1600,8 +1622,9 @@ async function run() {
     const minutes = muteMinutes === null ? DEFAULT_MUTE_MINUTES : muteMinutes;
     const state = setMuted(true, minutes);
     // Muting has to silence what is playing right now, not just the next
-    // prompt - the whole point is that a call is already ringing.
-    const stopped = require("./hooks").stopDaemon();
+    // prompt - the whole point is that a call is already ringing. The turns
+    // in flight are kept: they still finish, log and show in --state.
+    const stopped = require("./hooks").stopDaemon({ keepSessions: true });
 
     console.log(`\x1b[33m🔇 Muted ${muteRemainingText(state)}.\x1b[0m`);
     if (stopped) console.log(`  Stopped the player that was running.`);

package/src/hooks.js

@@ -220,7 +220,9 @@ const TARGETS = {
       interrupt: "Interrupt",
       end: "SessionEnd"
     },
-    entry: (command) => ({ hooks: [{ type: "command", command, timeout: 5 }] }),
+    // Codex caps SessionEnd and Interrupt hooks at 3s (SESSION_END_MAX_TIMEOUT_SEC,
+    // discovery.rs) and warns on every run when one asks for more.
+    entry: (command, event) => ({ hooks: [{ type: "command", command, timeout: event === "SessionEnd" || event === "Interrupt" ? 3 : 5 }] }),
     commands: (entry) => (entry.hooks || []).map((h) => h.command),
     seed: () => ({}),
     // Codex records a trusted_hash per hook in config.toml and asks before
@@ -384,6 +386,82 @@ function expectedEvents(id) {
   return [ev.start, ev.stop, ...(ev.wait || []), ...(ev.resume || []), ev.failure, ev.end, ev.interrupt].filter(Boolean);
 }
 
+/**
+ * The agents that load this repository as a plugin, and the hooks file each
+ * one reads. Copilot CLI loads `.claude-plugin/` manifests and Qwen Code
+ * converts the plugin on install (copying the folder, substituting
+ * CLAUDE_PLUGIN_ROOT), so both read Claude Code's hooks/hooks.json. Codex
+ * 0.160 would too, but Claude Code's validator rejects an event it does not
+ * know ("hooks.Interrupt: Invalid key in record") and then loads none of the
+ * file, so Codex's Interrupt cannot live there: `.codex-plugin/plugin.json`,
+ * which Codex reads before `.claude-plugin/` and Claude Code never reads,
+ * points Codex at a file of its own. Gemini CLI has its own extension format
+ * and is not one of these.
+ */
+const PLUGIN_FILES = {
+  "hooks/hooks.json": ["claude", "copilot", "qwen"],
+  "hooks/codex.json": ["codex"]
+};
+const PLUGIN_AGENTS = Object.values(PLUGIN_FILES).flat();
+
+const SLOT_ACTION = { start: "hook-start", stop: "hook-stop", failure: "hook-stop", wait: "hook-wait", resume: "hook-resume", end: "hook-end", interrupt: "hook-end" };
+
+/**
+ * Every event the given agents fire, with the one action it runs. One file
+ * can serve several agents, so it carries the union; an event an agent does
+ * not use there is dropped at runtime by `--event` (see runHookAction).
+ * Throws if two agents would need different actions for one event name,
+ * since the file could not serve both.
+ */
+function pluginHookEvents(agents) {
+  const actions = new Map();
+  for (const id of agents) {
+    for (const [slot, value] of Object.entries(TARGETS[id].events)) {
+      if (!SLOT_ACTION[slot]) continue; // `tool` is reactive mode, an --install-hooks option
+      for (const event of [].concat(value)) {
+        const prior = actions.get(event);
+        if (prior && prior !== SLOT_ACTION[slot]) throw new Error(`${event}: ${prior} for one agent, ${SLOT_ACTION[slot]} for ${id}`);
+        actions.set(event, SLOT_ACTION[slot]);
+      }
+    }
+  }
+  return actions;
+}
+
+/**
+ * A plugin hooks file (see PLUGIN_FILES), generated so it cannot drift from
+ * TARGETS. Agents sharing a file share an entry shape, so the first one's is
+ * used. `script` is the CLI's path as the host spells it: Gemini's extension
+ * substitutes ${extensionPath} itself, the others leave CLAUDE_PLUGIN_ROOT to
+ * the shell.
+ */
+function pluginHooksFile(agents, script = "${CLAUDE_PLUGIN_ROOT}/bin/vibeaudio.js") {
+  const hooks = {};
+  for (const [event, action] of pluginHookEvents(agents)) {
+    hooks[event] = [TARGETS[agents[0]].entry(`node "${script}" --${action} --plugin --event ${event}`, event)];
+  }
+  return { hooks };
+}
+
+/**
+ * Which agent is running a plugin hook, from the environment each one sets:
+ * Copilot CLI sets COPILOT_PLUGIN_ROOT (its changelog), Qwen Code sets
+ * QWEN_PROJECT_DIR for every hook (hookRunner.ts), Gemini CLI sets
+ * GEMINI_PROJECT_DIR for its extension's hooks (hookRunner.ts), and Codex sets
+ * PLUGIN_ROOT (discovery.rs). Claude Code sets none of these, only
+ * CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA / CLAUDE_PROJECT_DIR (2.1.195's
+ * bundle). Copilot also sets PLUGIN_ROOT, so it is checked first.
+ * ponytail: a variable exported in the user's own shell would leak into
+ * hooks and misattribute them; none of these names is one a user sets.
+ */
+function pluginAgent(env = process.env) {
+  if (env.COPILOT_PLUGIN_ROOT) return "copilot";
+  if (env.QWEN_PROJECT_DIR) return "qwen";
+  if (env.GEMINI_PROJECT_DIR) return "gemini"; // after Qwen, a fork that sets it too
+  if (env.PLUGIN_ROOT) return "codex";
+  return "claude";
+}
+
 function settingsPath() {
   return TARGETS.claude.file();
 }
@@ -456,14 +534,25 @@ function daemonPlaying() {
 
 /**
  * Stops the player. `keepSessions` leaves the session files alone: the hooks
- * use it because they decide per session what is still going on. Every other
- * stop (--stop, --mute, uninstall) ends everything, or a later tool call would
- * resume music nobody is waiting for.
+ * use it because they decide per session what is still going on, and --mute
+ * because a mute is about sound - the turns are still in flight, and should
+ * still reach --state, --events and --report. --stop and uninstall end
+ * everything, or a later tool call would resume music nobody is waiting for;
+ * each session dropped gets an `ended` event with that `reason`, or an
+ * --events consumer would show it working forever (#24).
  */
-function stopDaemon({ keepSessions = false } = {}) {
+function stopDaemon({ keepSessions = false, reason = "stop" } = {}) {
   const pid = readPid();
   fs.rmSync(PID_FILE, { force: true });
-  if (!keepSessions) fs.rmSync(SESSIONS_DIR, { recursive: true, force: true });
+  if (!keepSessions) {
+    // Removed before its event, so each line's status is what it left behind
+    // and the last one reads idle.
+    for (const s of listSessions()) {
+      fs.rmSync(sessionFile(s.id), { force: true });
+      emitEvent("ended", s.id, s.project, { reason });
+    }
+    fs.rmSync(SESSIONS_DIR, { recursive: true, force: true });
+  }
   if (pid === null || !isOurDaemon(pid)) return false;
 
   try {
@@ -800,6 +889,12 @@ function runDaemon(genre, volume, { reactive = false, volumeSource = null } = {}
   setTimeout(shutdown, MAX_DAEMON_MS);
 
   setInterval(() => {
+    // The pid file names the one daemon that owns the speakers. Two prompts
+    // at once can each find none running and spawn one; the last to write the
+    // file wins, and the other must not play over it (#42).
+    // ponytail: up to one poll of doubled audio; claim the pid file with an
+    // exclusive create before spawning if that ever matters.
+    if (readPid() !== process.pid) return shutdown();
     // A volume saved while this plays reaches it now, not at the next prompt.
     if (volumeSource) player.setVolume(volumeSource());
     if (sweep()) return;
@@ -1145,7 +1240,7 @@ function setHook(hooks, event, command, id) {
   // keeps the existing entries at their original index, which is what Codex
   // keys its per-hook trust records by.
   const kept = (hooks[event] || []).filter((entry) => !isVibeHook(entry, id));
-  kept.push(target(id).entry(command));
+  kept.push(target(id).entry(command, event));
   hooks[event] = kept;
 }
 
@@ -1168,8 +1263,8 @@ function readVibeEntryCount(file, id) {
 }
 
 /** True when --install-hooks has already written our entries for Claude Code. */
-function userHooksInstalled(file = null) {
-  return readVibeEntryCount(file || TARGETS.claude.file(), "claude") > 0;
+function userHooksInstalled(file = null, id = "claude") {
+  return readVibeEntryCount(file || TARGETS[id].file(), id) > 0;
 }
 
 function loadSettings(file, t = null) {
@@ -1383,6 +1478,11 @@ module.exports = {
   claudeConfigDir,
   codexHome,
   expectedEvents,
+  PLUGIN_FILES,
+  PLUGIN_AGENTS,
+  pluginHookEvents,
+  pluginHooksFile,
+  pluginAgent,
   runDaemon,
   hookStart,
   hookStop,

package/src/player.js

@@ -23,7 +23,10 @@ const { hashString } = require("./synth/generator");
 const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
 
-const CACHE_ROOT = path.join(os.homedir(), ".vibeaudio", "cache");
+// VIBE_CACHE_DIR is internal: the suite points it at a temp directory, so it
+// neither races live hooks pruning the real cache nor evicts a real project's
+// audio (#38).
+const CACHE_ROOT = process.env.VIBE_CACHE_DIR || path.join(os.homedir(), ".vibeaudio", "cache");
 
 /**
  * The cache key has to change whenever the audio would, or existing users keep
@@ -189,21 +192,23 @@ function ensureCacheDir() {
  */
 function pruneStaleCache() {
   try {
-    for (const entry of fs.readdirSync(CACHE_ROOT, { withFileTypes: true })) {
-      const full = path.join(CACHE_ROOT, entry.name);
-      if (entry.isDirectory() && /^v\d/.test(entry.name) && entry.name !== path.basename(CACHE_DIR)) {
-        fs.rmSync(full, { recursive: true, force: true });
-      } else if (entry.isFile() && entry.name.endsWith(".wav")) {
-        fs.rmSync(full, { force: true });
-      }
-    }
+    removeCacheEntries(path.basename(CACHE_DIR));
   } catch (e) {
     // Pruning is best-effort; a stale cache is not worth failing a run over.
   }
 }
 
+// Only what we write - key directories, and loose WAVs from before keys - and
+// never the root itself: VIBE_CACHE_DIR may name a directory holding more.
+function removeCacheEntries(keep = null) {
+  for (const entry of fs.readdirSync(CACHE_ROOT, { withFileTypes: true })) {
+    const ours = entry.isDirectory() ? /^v\d/.test(entry.name) && entry.name !== keep : entry.isFile() && entry.name.endsWith(".wav");
+    if (ours) fs.rmSync(path.join(CACHE_ROOT, entry.name), { recursive: true, force: true });
+  }
+}
+
 function clearCache() {
-  fs.rmSync(CACHE_ROOT, { recursive: true, force: true });
+  if (fs.existsSync(CACHE_ROOT)) removeCacheEntries();
   return CACHE_ROOT;
 }