vibeaudio 0.12.0 → 0.13.1

package/README.md

@@ -11,6 +11,8 @@
 > **🔊 [Listen to every genre →](https://kiril6.github.io/vibeaudio/)** — hear all 10 genres, the tier escalation, and the three chimes, rendered from the real synth.
 
 > **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)).
 
 ---
 
@@ -18,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`.
@@ -27,6 +38,7 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 🎛️ **Music that follows the work** ([reactive mode](#reactive-mode-opt-in), opt-in). Calm while the agent reads, fuller while it edits, busiest when it runs commands or hands work to sub-agents — you can hear *what* it's doing, not just for how long.
 * 🌅 **It fades, it doesn't cut.** On macOS the music eases in and out instead of starting and stopping mid-note, and `vibe --volume` reaches music that is already playing within a second.
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
+* 💓 **A heartbeat when an agent looks stuck.** If 4 of a session's last 8 tool calls fail — the test-edit-test loop that goes nowhere — a soft pulse on the music's tonic joins the music until things start passing again. It's rare by design: on 4,497 real turns it fired in under 1%.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
 * 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code and Windsurf**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
 
@@ -248,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` |
@@ -262,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` |
@@ -280,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>
@@ -306,13 +320,29 @@ 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.
 
+### As a Claude Code plugin
+
+If Claude Code is the only agent you use, the plugin installs the same hooks with no npm step:
+
+```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).
+
+- **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`.
+- **Not reactive.** `--reactive` is an `--install-hooks` option; the plugin doesn't carry it.
+
 ### `/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
@@ -368,14 +398,24 @@ Hooks log each finished turn — which project, how long, how it ended, and how
   You waited        3h 55m  on agents, 7m 51s per turn
   Agents waited     5m 35s  on you — permission dialogs and questions
   Typical turn      2m 57s  median
+  Back to it        41s  median from done to your next prompt, 27 times
+                    32s with a chime  1m 50s without (muted or --no-chime)
 ```
 
-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. 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.
+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.
 
 ### 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.
 
+### When an agent looks stuck
+
+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.
+
+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.
+
 ### Reactive mode (opt-in)
 
 ```bash
@@ -409,6 +449,35 @@ Changes land at the next loop boundary, so it shifts musically rather than cutti
 
 ---
 
+### Build on it: `vibe --state` and `vibe --events`
+
+The hard part of VibeAudio isn't the music. It's turning eight agents' different hook events into one set of states that mean the same thing everywhere. The music is one consumer of those states, and anything else can be another: a smart light, a menu bar icon, a tmux status line, a Stream Deck key.
+
+```bash
+vibe --state
+# {"v":1,"status":"waiting","sessions":[{"session":"…","project":"/work/api","state":"waiting","since":1791026124771,"tool":"Bash"}]}
+```
+
+Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiting` (on you: a permission dialog or a question). `status` is the machine's overall state: the most urgent of its sessions, in the order `waiting` > `stuck` > `working` > `idle`. One session waiting on you matters more than three working.
+
+`vibe --events` prints that snapshot once, then a JSON line for every change, as it happens:
+
+```json
+{"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:
+
+```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
+vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | while read p; do say "$(basename "$p") needs you"; done
+```
+
+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)
 
 **Claude Code, [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com/docs/hooks), [Grok](https://docs.x.ai/build/features/hooks), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Copilot CLI](https://docs.github.com/en/copilot/reference/hooks-configuration), [Qwen Code](https://github.com/QwenLM/qwen-code) and [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) have hook systems, and `--install-hooks` writes to all eight** — use [hooks](#-agent-hooks-no-wrapper-needed) there, they're strictly better. This section is for everything else. MCP is the way in: it's plain stdio JSON-RPC, so the setup is identical everywhere and only the config file differs.
@@ -587,6 +656,8 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--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 |
 | `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
+| `--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 | — |
 | `--stop` | Stop the background player, then exit | — |
 | `--mute [minutes]` | Silence everything for a call, then exit | `60` min (`0` = until unmuted) |
 | `--unmute` | Resume normal playback, then exit | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.12.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",
@@ -10,6 +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",
     "postinstall": "node scripts/postinstall.js"
   },
   "publishConfig": {

package/src/cli.js

@@ -78,6 +78,8 @@ Procedural focus music while your AI coding tools think.
       --status                 Show what is installed, running and detected, then exit
       --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes or needs you (off by default)
       --report [days]          How long you waited on agents, and where (default: 7 days)
+      --state                  Print what every agent is doing as JSON: idle, working, stuck or waiting
+      --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
       --mute [minutes]         Silence everything for a call (default: 60 min, 0 = until unmuted)
@@ -174,6 +176,8 @@ function parseArgs(argv) {
   let render = null;
   let clearCacheFlag = false;
   let statusFlag = false;
+  let stateFlag = false;
+  let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
   let reportDays = null;
@@ -184,6 +188,7 @@ function parseArgs(argv) {
   let mcp = false;
   let reactive = false;
   let followVolume = false;
+  let plugin = false;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -288,6 +293,13 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--state" || arg === "--events") {
+      if (arg === "--state") stateFlag = true;
+      else eventsFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--report") {
       // Optional window in days, like --mute's minutes: `vibe --report 30`.
       i += 1;
@@ -361,6 +373,14 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Internal, set by the plugin's hooks.json: yield to hooks that
+    // --install-hooks already wrote, so both being present is not a double chime.
+    if (arg === "--plugin") {
+      plugin = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--dry-run") {
       dryRun = true;
       i += 1;
@@ -461,6 +481,8 @@ function parseArgs(argv) {
     render,
     clearCache: clearCacheFlag,
     status: statusFlag,
+    state: stateFlag,
+    events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
     report: reportDays,
@@ -471,6 +493,7 @@ function parseArgs(argv) {
     mcp,
     reactive,
     followVolume,
+    plugin,
     dryRun,
     tools,
     typed,
@@ -577,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 });
@@ -747,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
@@ -860,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 {
@@ -872,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);
             });
           });
         }
@@ -926,10 +962,12 @@ function formatDuration(ms) {
  * The summary of ~/.vibeaudio/history.jsonl. "You waited" is the agent's own
  * working time - a turn's length minus the stretches it spent blocked on a
  * dialog of yours - because the two are different complaints: one is the
- * agent being slow, the other is you being away.
+ * agent being slow, the other is you being away. "Back to it" is the other
+ * direction: how long a finished turn waited for your next prompt, with gaps
+ * over RETURN_WINDOW_MS read as breaks and left out.
  */
 function printReport(days, now = Date.now()) {
-  const { readTurns } = require("./history");
+  const { readTurns, returnTimes } = require("./history");
   const turns = readTurns(days, now);
   const dim = (s) => `\x1b[90m${s}\x1b[0m`;
   const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -968,6 +1006,19 @@ function printReport(days, now = Date.now()) {
   row("Typical turn", formatDuration(median), "median");
   row("Longest turn", formatDuration(longest.ms), label(longest));
 
+  // How fast you came back once a turn was done - the human half of the loop.
+  const middle = (xs) => xs.slice().sort((a, b) => a - b)[Math.floor(xs.length / 2)];
+  const gaps = returnTimes(turns);
+  if (gaps.length) {
+    row("Back to it", formatDuration(middle(gaps.map((g) => g.ms))), `median from done to your next prompt, ${gaps.length} ${gaps.length === 1 ? "time" : "times"}`);
+    // Only once both sides have enough to mean something; three turns is an anecdote.
+    const withChime = gaps.filter((g) => g.chimed === true).map((g) => g.ms);
+    const without = gaps.filter((g) => g.chimed === false).map((g) => g.ms);
+    if (withChime.length >= 5 && without.length >= 5) {
+      row("", `${formatDuration(middle(withChime))} with a chime`, `${formatDuration(middle(without))} without (muted or --no-chime)`);
+    }
+  }
+
   const byProject = new Map();
   for (const t of turns) {
     const p = byProject.get(label(t)) || { ms: 0, n: 0 };
@@ -1273,9 +1324,14 @@ 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, tools, dryRun, typed = {} }) {
+function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, 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;
+
   switch (action) {
     case "daemon":
       return hooks.runDaemon(genre, volume, { reactive, volumeSource: followVolume ? volumeNow : null });
@@ -1488,6 +1544,8 @@ async function run() {
     render,
     clearCache: shouldClear,
     status: showStatus,
+    state: showState,
+    events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
     report: reportDays,
@@ -1498,6 +1556,7 @@ async function run() {
     mcp,
     reactive,
     followVolume,
+    plugin,
     dryRun,
     tools,
     typed,
@@ -1515,7 +1574,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, tools, dryRun, typed });
+      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, 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`);
@@ -1579,6 +1638,18 @@ async function run() {
     return printDoctor();
   }
 
+  // Machine-readable, for lights, menu bars and status lines: see "Build on it" in the README.
+  if (showState) {
+    console.log(JSON.stringify(require("./hooks").agentState()));
+    return;
+  }
+
+  if (followEvents) {
+    process.stdout.on("error", () => process.exit(0)); // `vibe --events | head` closing the pipe is not an error.
+    require("./hooks").followEvents();
+    return;
+  }
+
   if (reportDays !== null) {
     return printReport(reportDays);
   }

package/src/history.js

@@ -1,8 +1,9 @@
 /**
  * A local log of finished turns - what `vibe --report` reads. One JSON object
  * per line in ~/.vibeaudio/history.jsonl: when the turn ended, which project,
- * how long it took, how much of that the agent spent blocked on you, and how
- * it ended. It never leaves the machine; VIBE_NO_HISTORY=1 turns it off.
+ * how long it took, how much of that the agent spent blocked on you, how it
+ * ended, which session it was and whether a chime announced it. It never
+ * leaves the machine; VIBE_NO_HISTORY=1 turns it off.
  */
 
 const fs = require("fs");
@@ -14,12 +15,12 @@ const MAX_BYTES = 1024 * 1024;
 const KEEP_LINES = 4000;
 
 /** Appends one turn. Never throws: a log is not worth failing a hook over. */
-function recordTurn({ project, ms, blockedMs = 0, outcome = "success", at = Date.now() }, file = HISTORY_FILE) {
+function recordTurn({ project, ms, blockedMs = 0, outcome = "success", session, chimed, at = Date.now() }, file = HISTORY_FILE) {
   if (process.env.VIBE_NO_HISTORY) return false;
   if (!Number.isFinite(ms) || ms < 0) return false;
   try {
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.appendFileSync(file, `${JSON.stringify({ at, project, ms, blockedMs: Math.min(Math.max(blockedMs, 0), ms), outcome })}\n`);
+    fs.appendFileSync(file, `${JSON.stringify({ at, project, ms, blockedMs: Math.min(Math.max(blockedMs, 0), ms), outcome, session, chimed })}\n`);
     // Bounded, so a year of use is still a small file. Rewritten rarely, from
     // the tail, so the newest turns are always the ones kept.
     if (fs.statSync(file).size > MAX_BYTES) {
@@ -54,4 +55,34 @@ function readTurns(days, now = Date.now(), file = HISTORY_FILE) {
   return turns;
 }
 
-module.exports = { HISTORY_FILE, recordTurn, readTurns };
+// A gap longer than this is a break - lunch, a meeting, the end of the day -
+// not someone coming back to a finished turn, and would swamp the median.
+const RETURN_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * How long each finished turn sat before the next prompt in the same session:
+ * the time it took you to come back. A turn's start is `at - ms`. Sessions,
+ * not projects, are what pair up - two agents in one repo interleave - so a
+ * line from before sessions were logged (or an `anon` one) falls back to its
+ * project. `chimed` is the finished turn's, since that is the chime you were
+ * answering.
+ */
+function returnTimes(turns) {
+  const groups = new Map();
+  for (const t of turns) {
+    const key = t.session && t.session !== "anon" ? `s:${t.session}` : `p:${t.project}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  const gaps = [];
+  for (const list of groups.values()) {
+    list.sort((a, b) => a.at - b.at);
+    for (let i = 1; i < list.length; i++) {
+      const ms = list[i].at - list[i].ms - list[i - 1].at;
+      if (ms >= 0 && ms <= RETURN_WINDOW_MS) gaps.push({ ms, chimed: list[i - 1].chimed });
+    }
+  }
+  return gaps;
+}
+
+module.exports = { HISTORY_FILE, RETURN_WINDOW_MS, recordTurn, readTurns, returnTimes };

package/src/hooks.js

@@ -25,6 +25,7 @@ const INTENSITY_FILE = path.join(STATE_DIR, "intensity");
 // them is working; each holds where its transcript began and, while paused for
 // the user, what will resume it.
 const SESSIONS_DIR = path.join(STATE_DIR, "sessions");
+const EVENTS_FILE = path.join(STATE_DIR, "events.jsonl");
 // Payloads that name no session share this one slot.
 const ANON_SESSION = "anon";
 const CLI_ENTRY = path.join(__dirname, "..", "bin", "vibeaudio.js");
@@ -152,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.
@@ -181,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),
@@ -345,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();
 }
@@ -452,7 +491,7 @@ function newTurn(raw) {
   const payload = parsePayload(raw);
   const transcript = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
   const offset = transcript ? fileSize(transcript) : 0;
-  return { session: String(payloadSession(payload) || ""), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
+  return { session: String(payloadSession(payload) || ""), project: payload.cwd || process.cwd(), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
 }
 
 const BLOCK_LOOKBACK_MS = 3000;
@@ -545,6 +584,102 @@ function listSessions() {
 // Working, as opposed to paused for the user.
 const working = (sessions) => sessions.filter((s) => s.waiting == null);
 
+// "Stuck": STUCK_FAILURES of a session's last STUCK_WINDOW tool calls failed.
+// Measured on 4,497 real Claude Code turns (46,032 tool calls, 3.8% failing):
+// this fires in 0.9% of turns, at minute 3 by the median, and those turns ran
+// a median 3.3 minutes more - time someone could have stepped in. "3 of 8"
+// fired in 2.4%, and "3 in a row" misses the usual loop, where an edit that
+// succeeds sits between every failing test run. Rare is the point: a signal
+// that fires often is one people learn to tune out.
+const STUCK_WINDOW = 8;
+const STUCK_FAILURES = 4;
+const isStuck = (session) => (session.recent || []).filter(Boolean).length >= STUCK_FAILURES;
+
+/**
+ * The public face of the session files: what every agent on the machine is
+ * doing, in five words that mean the same thing whichever agent it is. The
+ * hard part of this project is mapping eight agents' hook events onto those
+ * states; the music is one consumer of them, and `vibe --state` / `--events`
+ * let anything else be another - a light, a menu bar, a tmux status line.
+ * `status` is the machine's: the most urgent of its sessions, since one
+ * session waiting on you matters more than three working.
+ */
+const STATE_RANK = ["idle", "working", "stuck", "waiting"];
+const sessionState = (s) => (s.waiting != null ? "waiting" : isStuck(s) ? "stuck" : "working");
+
+function agentState(sessions = listSessions()) {
+  const list = sessions.map((s) => ({
+    session: s.id,
+    project: s.project || null,
+    state: sessionState(s),
+    since: s.started || null,
+    ...(s.waiting ? { tool: s.waiting } : {})
+  }));
+  const status = list.reduce((a, s) => (STATE_RANK.indexOf(s.state) > STATE_RANK.indexOf(a) ? s.state : a), "idle");
+  return { v: 1, status, sessions: list };
+}
+
+const EVENTS_MAX_BYTES = 256 * 1024;
+
+/**
+ * Appends one transition to ~/.vibeaudio/events.jsonl, after the session file
+ * already reflects it, so `status` is the state the event left behind. Not
+ * gated by a mute: a mute silences sound, and a light watching this is not
+ * sound. Rotated to `.1` rather than trimmed in place, so a follower sees a
+ * fresh file instead of re-reading the lines a trim kept. Never throws.
+ */
+function emitEvent(event, session, project, extra = {}) {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    try {
+      if (fs.statSync(EVENTS_FILE).size > EVENTS_MAX_BYTES) fs.renameSync(EVENTS_FILE, `${EVENTS_FILE}.1`);
+    } catch (e) { /* no file yet */ }
+    const line = { v: 1, at: Date.now(), event, session, project: project || null, ...extra, status: agentState().status };
+    fs.appendFileSync(EVENTS_FILE, `${JSON.stringify(line)}\n`); // One write under PIPE_BUF: appends do not interleave.
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * `vibe --events`: the current state as one line, then every event as it is
+ * written, until killed. Polled rather than fs.watch'd, which is unreliable on
+ * the platforms this runs on; a quarter second is well inside a turn.
+ */
+function followEvents(write = (s) => process.stdout.write(s), pollMs = 250) {
+  write(`${JSON.stringify({ event: "state", at: Date.now(), ...agentState() })}\n`);
+  const stat = () => {
+    try {
+      const st = fs.statSync(EVENTS_FILE);
+      return { size: st.size, ino: st.ino };
+    } catch (e) {
+      return { size: 0, ino: null };
+    }
+  };
+  let { size: pos, ino } = stat();
+  let partial = "";
+  return setInterval(() => {
+    const now = stat();
+    if (now.ino !== ino || now.size < pos) {
+      ino = now.ino; // Rotated: the new file holds only what came after.
+      pos = 0;
+      partial = "";
+    }
+    if (now.size <= pos) return;
+    try {
+      const fd = fs.openSync(EVENTS_FILE, "r");
+      const buf = Buffer.alloc(now.size - pos);
+      fs.readSync(fd, buf, 0, buf.length, pos);
+      fs.closeSync(fd);
+      pos = now.size;
+      const lines = (partial + buf.toString("utf8")).split("\n");
+      partial = lines.pop();
+      for (const l of lines) if (l) write(`${l}\n`);
+    } catch (e) { /* removed between stat and open: next poll */ }
+  }, pollMs);
+}
+
 // Claude Code's entry for Esc / the stop button: a user message whose text is
 // "[Request interrupted by user]" or "... for tool use]".
 const INTERRUPT_MARK = "[Request interrupted by user";
@@ -627,6 +762,7 @@ function runDaemon(genre, volume, { reactive = false, volumeSource = null } = {}
       if (watchers.get(s.id)()) {
         fs.rmSync(sessionFile(s.id), { force: true });
         watchers.delete(s.id);
+        emitEvent("interrupted", s.id, s.project);
       }
     }
     return working(listSessions()).length > 0;
@@ -648,7 +784,9 @@ function runDaemon(genre, volume, { reactive = false, volumeSource = null } = {}
     // The same piece with more of it, as time escalation already does: two
     // sessions working is tier 2 at least, three or more is tier 3. Read at
     // each loop boundary, so it lands cleanly and eases off as they finish.
-    minTier: () => Math.min(3, working(listSessions()).length)
+    minTier: () => Math.min(3, working(listSessions()).length),
+    // A heartbeat under the music while any working session looks stuck.
+    tension: () => working(listSessions()).some(isStuck)
   });
   if (!started) process.exit(0);
 
@@ -697,7 +835,9 @@ function hookStart(genre, volume, { reactive = false, turn = null, follow = fals
   if (turn && turn.blocked) return null; // Rejected before it began: nothing to play for.
   const id = sessionId(turn && turn.session);
   // Before the spawn: the daemon reads it on startup.
-  writeSession(id, { transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null, started: Date.now(), blockedMs: 0 });
+  const project = (turn && turn.project) || process.cwd();
+  writeSession(id, { project, transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null, started: Date.now(), blockedMs: 0 });
+  emitEvent("started", id, project);
   if (working(listSessions()).some((s) => s.id !== id) && daemonRunning()) return readPid();
 
   stopDaemon({ keepSessions: true });
@@ -809,11 +949,14 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   const session = readSession(id);
   const tracked = session !== null;
   fs.rmSync(sessionFile(id), { force: true });
+  if (tracked) emitEvent("finished", id, parsePayload(raw).cwd || session.project, { outcome });
   if (session && Number.isFinite(session.started)) {
     const now = Date.now();
     // A turn that ends while still paused for you has been blocked since then.
     const blockedMs = (session.blockedMs || 0) + (session.waiting != null && session.waitStart ? now - session.waitStart : 0);
-    recordTurn({ project: parsePayload(raw).cwd || process.cwd(), ms: now - session.started, blockedMs, outcome, at: now });
+    // ponytail: assumes a playback backend exists; a machine with none hears no music either.
+    const chimed = !noChime && !playbackDisabled();
+    recordTurn({ project: parsePayload(raw).cwd || process.cwd(), ms: now - session.started, blockedMs, outcome, session: id, chimed, at: now });
   }
 
   // The music is every working session's, so it ends with the last of them.
@@ -873,6 +1016,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   if (!session || session.waiting != null) return false;
 
   writeSession(id, { ...session, waiting: waitKey(raw), waitStart: Date.now() });
+  emitEvent("waiting", id, session.project, waitKey(raw) ? { tool: waitKey(raw) } : {});
   if (working(listSessions()).length === 0) stopDaemon({ keepSessions: true });
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
@@ -894,15 +1038,34 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * job. Match on tool_input as well if that ever shows up in practice.
  */
 function hookResume(raw, genre, volume, { reactive = false, follow = false } = {}) {
-  const id = sessionId(payloadSession(parsePayload(raw)));
+  const payload = parsePayload(raw);
+  const id = sessionId(payloadSession(payload));
   const session = readSession(id);
-  if (!session || session.waiting == null) return false; // Not waiting - the common case, on every tool call.
+  if (!session) return false;
+
+  // Every tool call lands here, so this is where the stuck signal is kept.
+  // An interrupt is the user stopping a tool, not the tool failing.
+  // ponytail: two parallel tool calls in one session can each read, then write,
+  // and one result is lost. A heuristic over eight calls survives that.
+  const failed = payload.hook_event_name === "PostToolUseFailure" && !payload.is_interrupt;
+  const recent = [...(session.recent || []), failed ? 1 : 0].slice(-STUCK_WINDOW);
+  const next = { ...session, recent };
+  const crossing = isStuck(next) === isStuck(session) ? null : isStuck(next) ? "stuck" : "recovered";
+  if (crossing === "stuck") notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+
   // An empty key is a wait that named nothing (a Notification): the next tool
   // to finish is the first sign of work carrying on.
-  if (session.waiting !== "" && session.waiting !== waitKey(raw)) return false;
+  const resumes = session.waiting != null && (session.waiting === "" || session.waiting === waitKey(raw));
+  if (!resumes) {
+    writeSession(id, next);
+    if (crossing) emitEvent(crossing, id, session.project);
+    return false; // Not waiting - the common case, on every tool call.
+  }
 
   const blockedMs = (session.blockedMs || 0) + (session.waitStart ? Date.now() - session.waitStart : 0);
-  writeSession(id, { ...session, waiting: null, waitStart: null, blockedMs });
+  writeSession(id, { ...next, waiting: null, waitStart: null, blockedMs });
+  emitEvent("resumed", id, session.project);
+  if (crossing) emitEvent(crossing, id, session.project);
   if (!daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
   return true;
 }
@@ -918,9 +1081,11 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false } = {
  */
 function hookEnd(raw) {
   const id = sessionId(payloadSession(parsePayload(raw)));
-  if (!readSession(id)) return false;
+  const session = readSession(id);
+  if (!session) return false;
 
   fs.rmSync(sessionFile(id), { force: true });
+  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 });
@@ -1002,6 +1167,11 @@ 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 loadSettings(file, t = null) {
   if (!fs.existsSync(file)) return { settings: t ? t.seed() : {}, raw: null };
   const raw = fs.readFileSync(file, "utf8");
@@ -1114,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);
@@ -1129,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() {
@@ -1208,12 +1380,20 @@ function uninstallHooks(file = null, { id = "claude" } = {}) {
 
 module.exports = {
   shellQuote,
+  claudeConfigDir,
+  codexHome,
+  expectedEvents,
   runDaemon,
   hookStart,
   hookStop,
   hookTool,
   hookWait,
   hookResume,
+  isStuck,
+  STUCK_WINDOW,
+  agentState,
+  followEvents,
+  EVENTS_FILE,
   hookEnd,
   newTurn,
   outcomeFromPayload,
@@ -1231,6 +1411,7 @@ module.exports = {
   uninstallHooks,
   settingsPath,
   isVibeHook,
+  userHooksInstalled,
   hookEntries,
   installSlashCommand,
   uninstallSlashCommand,

package/src/player.js

@@ -20,6 +20,7 @@ const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
 const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
+const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
 
 const CACHE_ROOT = path.join(os.homedir(), ".vibeaudio", "cache");
@@ -617,7 +618,7 @@ function writeCacheFileAtomic(filePath, buffer) {
   }
 }
 
-function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0) {
+function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0, tension = false) {
   ensureCacheDir();
   const normalizedGenre = resolveGenre(genre);
   const safeTier = Math.max(1, Math.min(3, tier));
@@ -629,11 +630,14 @@ function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0)
   // into this opens on exactly the bar it has always opened on.
   const barSuffix = safeBar === 0 ? "" : `_b${safeBar}`;
   const dir = seedDir(seed);
-  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${barSuffix}${gainSuffix(gain)}.wav`);
+  // The stuck heartbeat is its own file, rendered only once an agent is stuck.
+  const tensionSuffix = tension ? "_x" : "";
+  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${barSuffix}${tensionSuffix}${gainSuffix(gain)}.wav`);
 
   if (!fs.existsSync(filePath)) {
     fs.mkdirSync(dir, { recursive: true });
-    writeCacheFileAtomic(filePath, applyGain(generateLoop(normalizedGenre, safeTier, seed >>> 0, safeBar), gain));
+    const loop = generateLoop(normalizedGenre, safeTier, seed >>> 0, safeBar);
+    writeCacheFileAtomic(filePath, applyGain(tension ? addTension(loop, GENRE_KEYS[normalizedGenre]) : loop, gain));
     pruneSeedDirs();
   }
 
@@ -728,6 +732,7 @@ class AudioPlayer {
     this.seed = projectSeed();
     this.intensity = null;
     this.minTier = null;
+    this.tension = null;
     this.currentTier = 1;
     this.bar = 0;
     this.nextTimer = null;
@@ -738,7 +743,7 @@ class AudioPlayer {
    * Returns true if playback actually started. Restarts when called with
    * different settings while playing, so a genre switch is not silently dropped.
    */
-  start(genre = "lofi", volume = 0.42, { maxDurationMs = null, intensity = null, minTier = null } = {}) {
+  start(genre = "lofi", volume = 0.42, { maxDurationMs = null, intensity = null, minTier = null, tension = null } = {}) {
     const resolved = resolveGenre(genre);
     const targetVolume = Math.max(0.05, Math.min(1.0, volume));
 
@@ -762,6 +767,7 @@ class AudioPlayer {
     this.bar = 0; // Every run opens on the project's own bar.
     this.intensity = intensity;
     this.minTier = minTier;
+    this.tension = tension;
 
     installExitHook();
     activePlayers.add(this);
@@ -800,7 +806,8 @@ class AudioPlayer {
     // never both, or the volume would be applied twice.
     const backend = detectPlayer();
     const gain = bakedGain(backend, this.volume);
-    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar);
+    // An agent that looks stuck adds a heartbeat, landing at this loop boundary.
+    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar, Boolean(this.tension && this.tension()));
     // Advanced after the choice, so the bar that plays first is bar 0.
     this.bar = (this.bar + 1) % LOOP_BARS;
     if (!(helperUsable(backend) && this.playViaHelper(audioFile, backend))) this.spawnLoop(audioFile, backend);

package/src/synth/tension.js

@@ -0,0 +1,67 @@
+/**
+ * The "stuck" layer: a soft heartbeat under the loop, played while an agent's
+ * recent tool calls keep failing. More of the same music would say "working
+ * hard", which is not the news; a pulse that was not there before changes the
+ * music's character, and a heartbeat is the most widely read tension cue there
+ * is. Pitched on the genre's tonic so it sits in the key rather than against it.
+ *
+ * Pure like every other synth module: a WAV buffer in, a new one out.
+ */
+
+const { noteToFreq, SAMPLE_RATE } = require("./generator");
+
+const BEAT_S = 1.1; // About 55 bpm: a resting heart, not a racing one.
+const DUB_DELAY_S = 0.24;
+const EDGE_S = 0.15; // Clear of the loop's boundary fades, so seams stay clean.
+const LEVEL = 0.22;
+
+// Laptop speakers roll off below ~120 Hz, and a pulse nobody hears is no
+// signal, so the tonic sits between 110 and 220 Hz with a second harmonic.
+function pulseFreq(key) {
+  const tonic = String(key || "A minor").split(" ")[0];
+  let f = noteToFreq(`${tonic}3`);
+  while (f > 220) f /= 2;
+  while (f < 110) f *= 2;
+  return f;
+}
+
+// One thump: a short pitch drop, like a soft kick, decaying in ~0.2s.
+function thump(t, f) {
+  if (t < 0 || t > 0.35) return 0;
+  const phase = f * t + (f * 0.5 * 0.04) * (1 - Math.exp(-t / 0.04)); // f*1.5 falling to f
+  const env = Math.min(1, t / 0.004) * Math.exp(-t / 0.075);
+  return env * (Math.sin(2 * Math.PI * phase) + 0.45 * Math.sin(4 * Math.PI * phase));
+}
+
+/** Mixes the heartbeat into a canonical 16-bit WAV (mono or stereo) and returns a new buffer. */
+function addTension(wav, key) {
+  if (wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF") {
+    throw new Error("addTension expects a canonical 44-byte-header WAV");
+  }
+  const channels = wav.readUInt16LE(22);
+  const rate = wav.readUInt32LE(24) || SAMPLE_RATE;
+  const frames = Math.floor((wav.length - 44) / (2 * channels));
+  const duration = frames / rate;
+  const f = pulseFreq(key);
+
+  // A whole number of beats per loop, so the pulse keeps time across loops.
+  const beats = Math.max(1, Math.round((duration - 2 * EDGE_S) / BEAT_S));
+  const period = (duration - 2 * EDGE_S) / beats;
+  const out = Buffer.from(wav);
+
+  for (let i = 0; i < frames; i++) {
+    const t = i / rate - EDGE_S;
+    if (t < 0 || t > duration - 2 * EDGE_S) continue;
+    const local = t % period;
+    const s = LEVEL * (thump(local, f) + 0.7 * thump(local - DUB_DELAY_S, f));
+    if (s === 0) continue;
+    for (let c = 0; c < channels; c++) {
+      const offset = 44 + (i * channels + c) * 2;
+      const mixed = Math.round(out.readInt16LE(offset) + s * 32767);
+      out.writeInt16LE(Math.max(-32768, Math.min(32767, mixed)), offset);
+    }
+  }
+  return out;
+}
+
+module.exports = { addTension, pulseFreq };