vibeaudio 0.13.0 → 0.13.1

package/README.md

@@ -20,6 +20,15 @@
 
 AI coding agents take 15–45 seconds to reason, read files and write code. Staring at a blank cursor feels slow; tabbing away means checking back to see if it's done. VibeAudio fills that gap with music while the agent thinks, and a chime when your output is ready to read.
 
+It is built as **calm technology**, in the sense of Mark Weiser and John Seely Brown's *Designing Calm Technology* (Xerox PARC, 1995): information that stays at the edge of your attention and only comes to the front when it matters. You stop noticing the music, but you notice when it changes.
+
+| Principle | In VibeAudio |
+| :--- | :--- |
+| Inform without demanding attention | The music sits in the background. What you notice is it *stopping*. |
+| Come to the front only when it matters | Chimes for done, failed and "needs you" only. The music doesn't react to every tool call unless you ask it to ([reactive mode](#reactive-mode-opt-in)). |
+| Make the background informative | Layers build as a turn runs long, and a heartbeat joins when an agent keeps failing. That fires in under 1% of turns, by design. |
+| Calm, not alarming | "Needs you" is a soft rising interval, not an alarm. A mute ends on its own after an hour. |
+
 **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`.
@@ -251,8 +260,8 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 
 | | File | Music starts | Music stops + chime | Reactive (opt-in) |
 | :--- | :--- | :--- | :--- | :--- |
-| **Claude Code** | `~/.claude/settings.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
-| **Codex** | `~/.codex/hooks.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Claude Code** | `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Codex** | `~/.codex/hooks.json` (or `$CODEX_HOME`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Cursor** | `~/.cursor/hooks.json` | `beforeSubmitPrompt` | `stop` | `preToolUse` |
 | **Grok** | `~/.grok/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Gemini CLI** | `~/.gemini/settings.json` | `BeforeAgent` | `AfterAgent` | `BeforeTool` |
@@ -265,7 +274,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | | Music pauses + "your turn" chime | Music resumes | Failure chime (API error) | Session closes mid-turn (silent) |
 | :--- | :--- | :--- | :--- | :--- |
 | **Claude Code** | `PermissionRequest`, `Elicitation` | `PostToolUse`, `PostToolUseFailure`, `ElicitationResult` | `StopFailure` | `SessionEnd` |
-| **Codex** | `PermissionRequest` | `PostToolUse` | — | — |
+| **Codex** | `PermissionRequest` | `PostToolUse` | — | `SessionEnd`, and `Interrupt` (Esc) |
 | **Gemini CLI** | `Notification` (tool permission) | `AfterTool` | — | `SessionEnd` |
 | **Copilot CLI** | `Notification` (permission prompt) | `PostToolUse`, `PostToolUseFailure` | — | `SessionEnd` |
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
@@ -283,6 +292,8 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **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. |
 | **Only Cursor can play the failure chime** | Its stop event reports whether the turn completed, aborted or errored. 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. |
+| **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. |
+| **Moved your config folder?** | VibeAudio follows `CLAUDE_CONFIG_DIR` and `CODEX_HOME` the way the agents do, so hooks (and `/vibe`) go where your agent actually reads them. Set the variable in the shell you run `vibe --install-hooks` from. |
 | **Grok and Copilot CLI get a file of their own** | Each reads every `*.json` in its `hooks/` directory, so VibeAudio writes `vibeaudio.json` rather than merging into anyone else's — which makes uninstalling it a delete, and leaves no backup file behind. Copilot's honours `COPILOT_HOME`. |
 
 </details>
@@ -309,7 +320,7 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI, Qwen Code or Windsurf session does the same hasn't been checked, so start a new session there to be sure.
 
-> **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json`. (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
+> **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-antigravity-via-mcp).)
 
 > **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.
 
@@ -331,7 +342,7 @@ It needs Node 18+ on your `PATH` (the hooks run `node`), and it also adds `/vibe
 
 ### `/vibe` inside Claude Code
 
-Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`), so you can control the music without leaving the session:
+Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`, or under `$CLAUDE_CONFIG_DIR`), so you can control the music without leaving the session:
 
 ```text
 /vibe                 what's installed and playing

package/package.json

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

package/src/cli.js

@@ -600,6 +600,7 @@ function installHookTargets(ids, genre, volume, reactive, dryRun = false, typed
     if (events.resume) console.log(`  ${events.resume[0].padEnd(19)}→ music resumes once you've answered`);
     if (events.failure) console.log(`  ${events.failure.padEnd(19)}→ music stops + failure chime (API error)`);
     if (events.end) console.log(`  ${events.end.padEnd(19)}→ music stops if that session started it`);
+    if (events.interrupt) console.log(`  ${events.interrupt.padEnd(19)}→ music stops silently when you interrupt`);
 
     if (id === "claude") {
       const slash = hooks.installSlashCommand({ dryRun });
@@ -770,6 +771,10 @@ function printStatus() {
     if (readVibeHooks(t.file(), t).some(({ command }) => /--genre /.test(command))) {
       console.log(`    \x1b[33m↑ pinned by an older install — vibe --install-hooks makes it follow Sound above\x1b[0m`);
     }
+    const absent = hooks.expectedEvents(id).filter((e) => !installed.some(({ event }) => event === e));
+    if (absent.length) {
+      console.log(`    \x1b[33m+ ${absent.join(", ")} added since this install — vibe --install-hooks picks them up\x1b[0m`);
+    }
   }
 
   // Background player
@@ -883,8 +888,11 @@ function doctorChecks() {
       const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
       for (const p of tokens.slice(0, 2)) if (!fs.existsSync(p)) missing.add(p);
     }
+    const absent = hooks.expectedEvents(id).filter((e) => !installed.some(({ event }) => event === e));
     if (missing.size) {
       add("fail", label, `points at a file that no longer exists: ${[...missing].join(", ")}`, "vibe --install-hooks");
+    } else if (absent.length) {
+      add("warn", label, `installed by an older version, missing ${absent.join(", ")}`, "vibe --install-hooks");
     } else if (installed.some(({ command }) => /--genre /.test(command))) {
       add("warn", label, "pinned to a genre/volume by an older install, which overrides your saved settings", "vibe --install-hooks");
     } else {
@@ -895,15 +903,20 @@ function doctorChecks() {
     // config.toml under "<file>:<event>:<group>:<index>".
     if (id === "codex") {
       let toml = "";
-      try { toml = fs.readFileSync(path.join(os.homedir(), ".codex", "config.toml"), "utf8"); } catch (e) { /* none yet */ }
+      try { toml = fs.readFileSync(path.join(hooks.codexHome(), "config.toml"), "utf8"); } catch (e) { /* none yet */ }
       const pending = [];
       try {
         const file = t.file();
+        // Codex canonicalizes CODEX_HOME before keying (find_codex_home()), so
+        // a symlinked one - /tmp on macOS - is recorded under its real path.
+        let real = file;
+        try { real = fs.realpathSync(file); } catch (e) { /* checked below */ }
         for (const [event, entries] of Object.entries(JSON.parse(fs.readFileSync(file, "utf8")).hooks || {})) {
           (entries || []).forEach((entry, g) => {
             t.commands(entry).forEach((command, i) => {
-              const key = `${file}:${event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()}:${g}:${i}`;
-              if (hooks.VIBE_HOOK_FLAG.test(command || "") && !toml.includes(`"${key}"`)) pending.push(event);
+              const suffix = `:${event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()}:${g}:${i}`;
+              const trusted = [file, real].some((f) => toml.includes(`"${f}${suffix}"`));
+              if (hooks.VIBE_HOOK_FLAG.test(command || "") && !trusted) pending.push(event);
             });
           });
         }

package/src/hooks.js

@@ -153,15 +153,35 @@ const MAX_DAEMON_MS = 15 * 60 * 1000;
  * - failure: a turn ending in error *instead of* the stop event
  * - end:     the session closing, which can cut a turn off before stop
  *
+ * - interrupt: the user stopped the turn (Esc), a silent end like `end`
+ *
  * `seed` is the root object to write when the file does not exist yet. Cursor
  * and Copilot require a schema version; Codex rejects unknown root keys
  * outright, so nothing may be added there beyond `hooks`.
  */
+/**
+ * Where Claude Code and Codex keep their config. Both move with an env var,
+ * and a user who sets one has hooks read from there only: writing to the
+ * default path left VibeAudio installed in a file nothing read, and silent.
+ * Claude Code: `CLAUDE_CONFIG_DIR ?? ~/.claude`, NFC-normalized (cn() in
+ * 2.1.195's bundle; settings.json and commands/ both live under it).
+ * Codex: `CODEX_HOME`, empty treated as unset, else `~/.codex`
+ * (find_codex_home(), 0.160 source). Empty is unset for both here, so an
+ * exported-but-blank variable cannot turn the path relative.
+ */
+function claudeConfigDir() {
+  return (process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")).normalize("NFC");
+}
+
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+
 const TARGETS = {
   claude: {
     name: "Claude Code",
     cmd: "claude",
-    file: () => path.join(os.homedir(), ".claude", "settings.json"),
+    file: () => path.join(claudeConfigDir(), "settings.json"),
     // - wait: PermissionRequest fires when the dialog is shown in the terminal,
     //   the SDK (desktop app, IDEs) and print mode alike - Notification's
     //   permission_prompt is raised by the terminal UI alone, after 6s idle.
@@ -182,17 +202,23 @@ const TARGETS = {
   codex: {
     name: "Codex",
     cmd: "codex",
-    file: () => path.join(os.homedir(), ".codex", "hooks.json"),
+    file: () => path.join(codexHome(), "hooks.json"),
     // PermissionRequest runs only when Codex is about to ask for approval,
-    // with tool_name, and is present in 0.125's binary. Its docs describe
-    // Interrupt and SessionEnd too, but 0.125 has neither - and a strict parser
-    // meeting an event it does not know would take every hook down with it.
+    // with tool_name, and is present in 0.125's binary. SessionEnd arrived in
+    // 0.145 and Interrupt in 0.150 (source of each release tag). Listing them
+    // is safe on older versions: HookEventsToml has never denied unknown
+    // fields (checked 0.125 through 0.160), so an older Codex ignores an
+    // event it does not know - only the file's root is strict. Interrupt runs
+    // on the turn-abort path, not the one that runs Stop, with session_id,
+    // cwd and transcript_path.
     events: {
       start: "UserPromptSubmit",
       stop: "Stop",
       tool: "PreToolUse",
       wait: ["PermissionRequest"],
-      resume: ["PostToolUse"]
+      resume: ["PostToolUse"],
+      interrupt: "Interrupt",
+      end: "SessionEnd"
     },
     entry: (command) => ({ hooks: [{ type: "command", command, timeout: 5 }] }),
     commands: (entry) => (entry.hooks || []).map((h) => h.command),
@@ -346,6 +372,18 @@ function detectTargets() {
   });
 }
 
+/**
+ * Every event an install by this version writes for a target, `tool` aside
+ * (reactive mode only). A hook file is written once and outlives upgrades,
+ * so an event added in a later version - Codex's Interrupt and SessionEnd in
+ * 0.13.1 - never reaches someone who installed before it unless they
+ * reinstall. `--doctor` and `--status` compare against this to say so.
+ */
+function expectedEvents(id) {
+  const ev = TARGETS[id].events;
+  return [ev.start, ev.stop, ...(ev.wait || []), ...(ev.resume || []), ev.failure, ev.end, ev.interrupt].filter(Boolean);
+}
+
 function settingsPath() {
   return TARGETS.claude.file();
 }
@@ -1047,7 +1085,7 @@ function hookEnd(raw) {
   if (!session) return false;
 
   fs.rmSync(sessionFile(id), { force: true });
-  emitEvent("ended", id, session.project);
+  emitEvent(parsePayload(raw).hook_event_name === "Interrupt" ? "interrupted" : "ended", id, session.project);
   if (working(listSessions()).length === 0) {
     stopDaemon({ keepSessions: true });
     fs.rmSync(INTENSITY_FILE, { force: true });
@@ -1246,6 +1284,8 @@ function installHooks(genre = "lofi", volume = 0.4, file = null, { reactive = fa
   }
   if (ev.failure) setHook(settings.hooks, ev.failure, hookCommand("--hook-stop", genre, volume), id);
   if (ev.end) setHook(settings.hooks, ev.end, hookCommand("--hook-end", genre, volume), id);
+  // An interrupt ends the turn the same silent way a closed session does.
+  if (ev.interrupt) setHook(settings.hooks, ev.interrupt, hookCommand("--hook-end", genre, volume), id);
 
   const after = `${JSON.stringify(settings, null, 2)}\n`;
   if (!dryRun) fs.writeFileSync(file, after);
@@ -1261,7 +1301,7 @@ function installHooks(genre = "lofi", volume = 0.4, file = null, { reactive = fa
 const SLASH_MARK = "<!-- vibeaudio:slash-command -->";
 
 function slashCommandFile() {
-  return path.join(os.homedir(), ".claude", "commands", "vibe.md");
+  return path.join(claudeConfigDir(), "commands", "vibe.md");
 }
 
 function slashCommandText() {
@@ -1340,6 +1380,9 @@ function uninstallHooks(file = null, { id = "claude" } = {}) {
 
 module.exports = {
   shellQuote,
+  claudeConfigDir,
+  codexHome,
+  expectedEvents,
   runDaemon,
   hookStart,
   hookStop,