vibeaudio 0.14.0 → 0.14.2

package/README.md

@@ -1,5 +1,9 @@
 # 🎧 VibeAudio
 
+<p align="center">
+  <img src="docs/og.png?v=2" alt="VibeAudio — Focus music while your AI codes" width="720">
+</p>
+
 [![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/vibeaudio)](https://www.npmjs.com/package/vibeaudio) [![downloads](https://img.shields.io/npm/d18m/vibeaudio?label=downloads)](https://npm-stat.com/charts.html?package=vibeaudio) [![downloads/month](https://img.shields.io/npm/dm/vibeaudio)](https://npm-stat.com/charts.html?package=vibeaudio)
 
 > **Procedural focus music while your AI coding tools think.**
@@ -31,7 +35,8 @@ 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`.
+* 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no install scripts, 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.
@@ -48,7 +53,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 * 🛡️ **A grace window.** Fast commands stay 100% silent — music starts only past 1.5s (`--grace`).
 * 🪟 **Several sessions, one soundtrack.** Run as many terminals of the same agent as you like: the music plays while *any* of them is working, and each finishes with its own chime. One session ending, pausing for a permission dialog or being interrupted never cuts off another that's still going.
 * 🧮 **Honest exit codes.** Your command's status passes straight through (`130` on `Ctrl+C`), so `vibe claude && next-step` behaves exactly as it would without the wrapper.
-* 🌊 **Terminal title HUD.** A live ASCII wave and elapsed timer in the window title, where it can't corrupt a full-screen TUI.
+* 🌊 **Terminal title HUD.** A live ASCII wave and elapsed timer in the window title (`[ ♫ ▃▅▆▇█▇▆▃ lofi (0:24) ]`), where it can't corrupt a full-screen TUI.
 
 </details>
 
@@ -351,11 +356,16 @@ Codex asks you to approve the plugin's hooks once, as it does for any hook. Upda
 
 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).
 
+<details>
+<summary><b>Plugin details & coexistence with npm</b> — settings file, coexistence, and limitations</summary>
+
 - **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 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.
 
+</details>
+
 ### `/vibe` inside Claude Code
 
 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:
@@ -418,8 +428,13 @@ Hooks log each finished turn — which project, how long, how it ended, and how
                     32s with a chime  1m 50s without (muted or --no-chime)
 ```
 
+<details>
+<summary><b>How the report metrics & return times are calculated</b></summary>
+
 plus where the time went by project and, for windows up to two weeks, by day. "You waited" is the agent's own working time; the time it spent blocked on you is shown separately, because they are different problems. "Back to it" is the other direction: how long a finished turn sat before your next prompt in the same session — gaps over 30 minutes count as breaks and are left out. Once both sides have five turns, it is split by whether a chime announced the turn, so you can see what the chime is worth to you. The log stays on your machine, never leaves it, is capped at about 1 MB, and `VIBE_NO_HISTORY=1` turns it off. Only hook-driven turns are logged — a command wrapped as `vibe <command>` is not, since its lifetime isn't the same thing as an agent's working time.
 
+</details>
+
 ### The chime is in the music's key
 
 The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
@@ -428,10 +443,15 @@ The success chime is the tonic chord of whatever key your genre sits in — C ma
 
 The worst stretch of agent work is twenty minutes of the same thing failing while the music says all is well. So when **4 of a session's last 8 tool calls fail**, a soft heartbeat — two low beats about once a second, on the tonic of your genre — joins the music at the next loop boundary, and leaves once enough calls succeed. With `--notify` on, you also get one banner when the session crosses the line ("api: looks stuck"), not one per failure.
 
+<details>
+<summary><b>How the stuck threshold was calibrated (4,497 turns analyzed)</b></summary>
+
 The threshold was picked against 4,497 real Claude Code turns (46,032 tool calls). It fires in about 1% of turns, at around minute 3, and those turns typically ran for another 3 minutes — time you could have spent stepping in. "3 in a row" was rejected because the usual loop has a successful edit between every failing test run. Each new prompt starts with a clean slate, and an interrupt (Esc) never counts as a failure.
 
 It needs the agent to report failed tool calls, which **Claude Code, Copilot CLI and Qwen Code** do (`PostToolUseFailure`). Codex, Cursor, Gemini, Grok and Windsurf don't, so for them the music never adds the heartbeat.
 
+</details>
+
 ### Reactive mode (opt-in)
 
 ```bash
@@ -482,16 +502,27 @@ 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` (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:
+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.
 
+#### 📟 Status Bar & Desktop Integrations
+
+**tmux status bar** — show overall agent state (`waiting`, `stuck`, `working`, or `idle`):
 ```bash
-# tmux: show the state in the status bar
 set -g status-right '#(vibe --state | jq -r .status)'
+```
 
-# macOS: say it out loud when any agent needs you
+**macOS speech alert** — announce out loud whenever an agent stops to ask for your input:
+```bash
 vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | while read p; do say "$(basename "$p") needs you"; done
 ```
 
+**Starship prompt** — custom indicator in `~/.config/starship.toml`:
+```toml
+[custom.vibe]
+command = "vibe --state | jq -r 'if .status != \"idle\" then \"🎧 \" + .status else \"\" end'"
+when = "command -v vibe >/dev/null"
+```
+
 The stream is a local file (`~/.vibeaudio/events.jsonl`, rotated at 256 KB), so it never leaves your machine. It keeps updating while you're muted, because a mute silences sound and a light isn't sound. The `v` field is the format version, and any breaking change will increment it.
 
 ## 🖥️ Everything Else (Claude Desktop, Antigravity… via MCP)
@@ -574,7 +605,7 @@ Playback stops automatically if the desktop client disconnects, and caps out aft
 
 ## 🎨 Music Genres
 
-VibeAudio includes **8 procedural music styles** synthesized entirely in code:
+VibeAudio includes **10 procedural sound styles** synthesized entirely in code:
 
 | Genre | Style | Vibe |
 | :--- | :--- | :--- |
@@ -590,7 +621,8 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 | `ocean` | 🌊 **Ocean** | Low surf on a slow swell that rises and drains — **no melody at all** |
 | `random` | 🎲 **Shuffle Mode** | Picks a surprise genre for the run — **never `drone`, `rain` or `ocean`** |
 
-**Aliases also work**, so you can ask for a genre the way you'd say it — `vibe --preview chill` is `lofi`:
+<details>
+<summary><b>Genre aliases</b> — you can ask for a genre the way you'd say it (<code>chill</code>, <code>retrowave</code>, <code>bossa</code>, <code>ambient</code>…)</summary>
 
 | Canonical | Also accepted |
 | :--- | :--- |
@@ -607,6 +639,8 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 
 Matching is case-insensitive, so `BOSSA` works too.
 
+</details>
+
 > **If any melody distracts you, use `drone`.** Every other genre plays something — notes, a progression, a bass line — and some people can't read while that happens. `drone` holds one low tone under a slow-breathing noise bed and never moves: closer to a fan or rainfall than to music. Tiers add weight rather than movement. If you want the fan-and-rainfall idea literally, `rain` and `ocean` are synthesized the same way (seeded noise, no recorded files): rain adds more droplets as the turn runs longer, ocean adds a second swell and then foam.
 >
 > **`piano` is the gentler version of that idea.** It still plays notes — two in eight seconds at tier 1 — but they're single struck tones with silence between them and nothing running underneath. Higher tiers fill the gaps rather than adding a groove. Try it before `drone` if you want *something* there.
@@ -746,7 +780,9 @@ It shouldn't. The cache key includes a hash of the synth sources, so changing a
 vibe --clear-cache
 ```
 
-**Silent when the agent runs on another machine over SSH**
+<details>
+<summary><b>Silent when the agent runs on another machine over SSH (socket forwarding)</b></summary>
+
 Sound plays on the machine where the agent runs, and a remote server usually has no sound card — so VibeAudio finds no player and stays quiet. You can hear it locally by forwarding a PulseAudio socket through the SSH connection: the remote `paplay` sends the audio back over SSH to your own speakers.
 
 This needs a PulseAudio-compatible sound server on **your local machine**: a Linux desktop (PipeWire and PulseAudio both provide one) or Windows with WSLg. macOS has none built in, so this route doesn't apply there.
@@ -768,6 +804,8 @@ This needs a PulseAudio-compatible sound server on **your local machine**: a Lin
 
 If the second connection fails with the socket "already in use", an earlier session left it behind: `rm /tmp/vibe-pulse.sock` on the server, or set `StreamLocalBindUnlink yes` in the server's `sshd_config`. If `paplay` says access denied, your local PulseAudio requires its cookie — copy `~/.config/pulse/cookie` to the same path on the server.
 
+</details>
+
 **Volume flag does nothing**
 Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change reaches music already playing within a second on macOS hooks (it eases there), at the next loop boundary elsewhere, and in the wrapper or MCP on their next run; `vibe --status` shows the volume in effect and what set it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.14.0",
+  "version": "0.14.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",
@@ -10,8 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
-    "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"
+    "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"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -23,7 +22,6 @@
   "files": [
     "bin/",
     "src/",
-    "scripts/postinstall.js",
     "README.md",
     "LICENSE"
   ],

package/src/hooks.js

@@ -889,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;

package/scripts/postinstall.js

@@ -1,50 +0,0 @@
-/**
- * The one line an install owes the user.
- *
- * `npm i -g vibeaudio` used to end in silence: nothing plays until hooks are
- * installed or a command is wrapped, so someone who installed it and then went
- * back to work heard nothing and concluded it was broken. This says what to
- * run next, once, at the only moment the user is definitely looking.
- *
- * It must never fail an install. Anything thrown here is npm's problem to
- * report and the user's to wonder about, so everything is wrapped and the exit
- * code is always 0 - a greeting is not worth a failed install.
- */
-// npm 7+ hides lifecycle-script stdout unless the script fails - measured on
-// npm 10, a global install printed only "added 1 package". The controlling
-// terminal is outside npm's pipe, so write there; stdout remains for when
-// there is no terminal (CI, Windows), where npm may or may not show it.
-function say(text) {
-  const fs = require("fs");
-  try {
-    const fd = fs.openSync("/dev/tty", "w");
-    fs.writeSync(fd, text + "\n");
-    fs.closeSync(fd);
-  } catch (e) {
-    console.log(text);
-  }
-}
-
-try {
-  // Local installs are a dependency of something else; their user is not here
-  // and not the one who would run `vibe`. CI and Docker set this too.
-  // No isTTY check: npm pipes lifecycle output often enough that gating on it
-  // would mean the hint never lands for the people who need it. A global
-  // install is already the narrow case - a dependency install sets this false.
-  if (process.env.npm_config_global === "true") {
-    const c = (code, text) => `\x1b[${code}m${text}\x1b[0m`;
-    say(`
-${c("1;36", "🎧 VibeAudio installed.")} Start here:
-
-  ${c("1", "vibe")}                   ${c("90", "guided setup: pick your agent, genre and volume")}
-
-Or skip the menu:
-
-  ${c("1", "vibe --install-hooks")}   ${c("90", "music follows your agent's thinking — Claude Code, Codex, Cursor…")}
-  ${c("1", "vibe npm test")}          ${c("90", "wrap any command that exits when it's done")}
-  ${c("1", "vibe --preview jazz")}    ${c("90", "hear a genre first")}
-`);
-  }
-} catch (e) {
-  // Deliberately silent: see above.
-}