vibeaudio 0.17.0 → 0.19.0

package/README.md

@@ -147,7 +147,7 @@ Want the music to follow what the agent is doing — calm while it reads, busies
 vibe --reactive --install-hooks
 ```
 
-Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you.
+Prefer a guided setup? Run `vibe` with nothing after it: a menu asks for your agent, genre and volume (press `p` to hear a genre first) and installs the hooks for you. Installing hooks doesn't start the agent: open it whenever you like, and the music plays from your first prompt. ("Just launch it" and "This session only" do start it.)
 
 Now run your agent normally, with no prefix. Music starts when you submit a prompt and stops with a chime when the agent finishes. [Details below.](#-agent-hooks-no-wrapper-needed)
 
@@ -269,10 +269,10 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 | **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` |
-| **Copilot CLI** | `~/.copilot/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
-| **Qwen Code** | `~/.qwen/settings.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Grok** | `~/.grok/hooks/vibeaudio.json` (or `$GROK_HOME`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Gemini CLI** | `~/.gemini/settings.json` (or `$GEMINI_CLI_HOME/.gemini`) | `BeforeAgent` | `AfterAgent` | `BeforeTool` |
+| **Copilot CLI** | `~/.copilot/hooks/vibeaudio.json` (or `$COPILOT_HOME`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Qwen Code** | `~/.qwen/settings.json` (or `$QWEN_HOME`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Windsurf** | `~/.codeium/windsurf/hooks.json` | `pre_user_prompt` | `post_cascade_response` | `pre_run_command` |
 | **Antigravity** | `~/.gemini/config/hooks.json`, under its own `vibeaudio` name | `PreInvocation` (the first of each prompt) | `Stop` | — never ([why](#antigravity-hooks)) |
 
@@ -302,7 +302,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Cursor and Antigravity say how a turn ended** | Cursor's stop event reports whether the turn completed, aborted or errored, and Antigravity's gives a termination reason, so an error plays the failure chime. Claude Code and Qwen Code send a separate `StopFailure` for an API error. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
 | <a id="antigravity-hooks"></a>**Antigravity never gets a pre-tool hook** | Its pre-tool hook has to approve or deny every tool call — one that answers nothing blocks the tool — so VibeAudio installs none, and `--reactive` does nothing there. It has no prompt event either: the start event fires before every model call, and VibeAudio starts the music on the first one of each prompt only. Its hooks live in `~/.gemini/config/hooks.json` under a name of their own, so your other named hooks there are never touched. Verified with the `agy` CLI; the desktop app reads the same file by Antigravity's own docs but hasn't been checked live. |
 | **Upgraded, and a new feature isn't there?** | Hooks are written into your agent's config once, at install time, and an upgrade doesn't touch them. When a new version listens for more events (0.13.1 added Codex's `Interrupt` and `SessionEnd`), `vibe --doctor` and `vibe --status` name what's missing, and `vibe --install-hooks` adds it. |
-| **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. |
+| **Moved your config folder?** | VibeAudio follows `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `GEMINI_CLI_HOME`, `QWEN_HOME` and `GROK_HOME` the way each agent does, so hooks (and `/vibe`) go where your agent actually reads them. Cursor and Windsurf have no such variable that we could confirm. 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>
@@ -522,7 +522,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` (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.
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it) and `announced` (from [`vibe --announce`](#-beyond-agents-vibe---announce), with `text` and `outcome`, and no session). 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
 
@@ -540,7 +540,9 @@ It is plain text on purpose: tmux and Starship do their own styling. It doesn't
 **tmux status bar:**
 ```bash
 set -g status-right '#(vibe --statusline)'
+set -g status-interval 5
 ```
+tmux re-runs `#(...)` every `status-interval` seconds, 15 by default, so without the second line a dialog can wait up to 15 seconds before the bar says so.
 
 **macOS speech alert** — announce out loud whenever an agent stops to ask for your input:
 ```bash
@@ -556,10 +558,53 @@ format = "([🎧 $output ]($style))"
 ```
 The parentheses matter: Starship hides a group whose variables are empty, so the 🎧 disappears with the text when idle. Put the icon in a `symbol` instead and it shows all the time. `vibe --statusline` takes about 40 ms, so running it on every prompt is fine.
 
-*Run on tmux 3.x and Starship 1.26.0, macOS arm64, Node 24: both showed `working`, `working ×2` and `waiting: web` as sessions started and waited, and nothing when idle. Not run on Linux or Windows.*
+**Webhook** — post `waiting` and `stuck` to anything that takes an HTTP request (a smart plug bridge, a Stream Deck plugin, Slack's incoming webhooks):
+```bash
+vibe --events | jq --unbuffered -c 'select(.event=="waiting" or .event=="stuck") | {event, project}' \
+  | while read -r line; do curl -s -X POST -H 'Content-Type: application/json' -d "$line" https://example.com/hook; done
+```
+The `select` also drops the snapshot `--events` prints first (its `event` is `state`), so only changes after you start it are sent: a session already waiting at that moment is not announced. For the current state, call `vibe --state` once.
+
+**Home Assistant (or any smart light)** — send the machine's overall state on every change, and let the receiving side choose the colour. Home Assistant takes this as a [webhook trigger](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger); replace the URL and the id:
+```bash
+vibe --events | jq --unbuffered -c 'select(.event != "state") | {status, event, project}' \
+  | while read -r line; do curl -s -X POST -H 'Content-Type: application/json' -d "$line" http://homeassistant.local:8123/api/webhook/vibeaudio; done
+```
+`status` is `idle`, `working`, `stuck` or `waiting`, already the most urgent across all your sessions, so the automation is a plain switch on one field (for example amber for `waiting`, red for `stuck`, off for `idle`) and never has to count sessions itself. A web request goes out on every change, so point it at a local bridge rather than a metered service.
+
+*Not covered yet: a macOS menu bar plugin (SwiftBar/xbar) and Linux desktop alerts. Neither has been run on a real setup, so neither is documented. `--notify` already raises a banner when a turn finishes or needs you.*
+
+*Verified on macOS arm64 with Node 24, tmux 3.7 and Starship 1.26 (the Home Assistant recipe: the request it sends, against a local stand-in server, was `{"status":"waiting","event":"waiting","project":"/work/api"}` on a permission dialog; not run against Home Assistant itself): the tmux and Starship segments showed `working`, `working ×2` and `waiting: web` and disappeared when idle; the `say` and webhook pipelines fired once per `waiting` event while the stream stayed open. Not run on Linux or Windows.*
 
 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.
 
+#### 🖥️ A live view: `vibe --dashboard`
+
+```bash
+vibe --dashboard        # serves http://127.0.0.1:4747 and opens it
+```
+
+![The VibeAudio dashboard: one waiting, one stuck and one working session, with the recent events below](docs/dashboard.png)
+
+One row per session (waiting first, then stuck, then working), with the project, the tool it's waiting on and how long it has been in that state, and a feed of recent events with failures and stuck sessions in red. It's built on `--events`, so it shows every agent VibeAudio hooks into, and it updates as things happen.
+
+It's **read-only and local**: it binds to `127.0.0.1` only, refuses any request whose `Host` isn't its own address (so a web page can't reach it through DNS rebinding), sends no CORS headers, and only answers `GET`, so there's nothing a page in another tab could trigger. It uses no external assets, and nothing leaves your machine. It runs in the foreground until Ctrl+C. `--port <n>` picks the port (4747 by default; if that's taken, a free one is used), and `--no-open` skips opening the browser.
+
+#### 🔔 Beyond agents: `vibe --announce`
+
+A CI run, a deploy, a long script that wasn't started through `vibe <command>`: the same chimes can say those finished too.
+
+```bash
+vibe --announce "CI green"                       # success chime
+vibe --announce "deploy" --outcome attention     # the "needs you" chime
+./deploy.sh; vibe --announce "deploy" --exit-code $?     # 0 is success, anything else failure
+gh run watch; vibe --announce "CI finished" --exit-code $?
+```
+
+It plays the chime for the outcome, shows the `--notify` banner if you have it on, and appends an `announced` event (`source: "cli"`, the text and the outcome) to `~/.vibeaudio/events.jsonl`, so a light or dashboard built on `--events` reacts too. It never starts or stops music and never touches an agent session. A mute silences the sound and banner but not the event, like every event.
+
+It always exits 0, so it can't turn a pipeline red, and the text is only ever passed as an argument, never through a shell. Text is capped at 200 characters, and the same text announced again within five seconds is dropped, so a loop can't machine-gun your speakers. `--no-chime` keeps it to the banner and event.
+
 ## 🖥️ Everything Else (Claude Desktop, VS Code… 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) [Windsurf](https://docs.devin.ai/desktop/cascade/hooks) and [Antigravity](https://antigravity.google/docs/hooks) have hook systems, and `--install-hooks` writes to all nine** — 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.
@@ -747,6 +792,8 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--statusline` | The same state as one plain line for tmux or a shell prompt (`working ×2`, `waiting: api`); prints nothing when idle | — |
 | `--state` | What every agent on the machine is doing, as one line of JSON: `idle`, `working`, `stuck` or `waiting` | — |
 | `--events` | Stream agent state changes as JSON lines, starting with the current state, until stopped | — |
+| `--dashboard` | Serve a read-only live view of every agent on this machine at `http://127.0.0.1:4747`, and open it. `--port <n>` and `--no-open` adjust it | — |
+| `--announce <text>` | Play the chime for something that isn't an agent (CI, a deploy, a script), then exit. Add `--outcome success\|failure\|attention` or `--exit-code $?` | `success` |
 | `--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.17.0",
+  "version": "0.19.0",
   "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",

package/src/cli.js

@@ -59,6 +59,7 @@ Procedural focus music while your AI coding tools think.
   vibe --genre 8bit sleep 5
   vibe --volume 30 npm test
   vibe --preview jazz
+  gh run watch; vibe --announce "CI finished" --exit-code $?   \x1b[90m# the chime for a CI run or a script\x1b[0m
   vibe --render                  \x1b[90m# save this repo's sound as a .wav to share\x1b[0m
   vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre)\x1b[0m
 
@@ -81,6 +82,12 @@ Procedural focus music while your AI coding tools think.
       --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
+      --announce <text>        Play the signals for something that is not an agent (CI, a deploy, a script), then exit
+      --outcome <o>            With --announce: success (default), failure or attention
+      --exit-code <n>          With --announce: 0 is success, anything else failure (use $?)
+      --dashboard              Serve a read-only live view of every agent on this machine, and open it
+      --port <n>               With --dashboard: the port (default ${require("./dashboard").DEFAULT_PORT}, else a free one)
+      --no-open                With --dashboard: do not open the browser
       --statusline             Print that as one plain line for tmux or a prompt; prints nothing when idle
       --events                 Stream agent state changes as JSON lines, until stopped
       --doctor                 Check the setup; each problem comes with its fix (exit 1 if any)
@@ -95,7 +102,7 @@ Procedural focus music while your AI coding tools think.
       --dry-run                With --install-hooks: show what would change, write nothing
       --uninstall-hooks        Remove the hooks again, from every agent
   -h, --help                   Show this help message
-      --version                Show version
+      --version                Show version (update with: npm i -g vibeaudio)
 
 \x1b[1mSETTINGS:\x1b[0m
   A genre or volume with no command after it is saved as your default:
@@ -108,15 +115,43 @@ Procedural focus music while your AI coding tools think.
   \x1b[1m--here\x1b[0m setting beats the global one, so a one-off
   \x1b[1mvibe --genre 8bit npm test\x1b[0m stays a one-off.
 
+\x1b[1mINTEGRATIONS:\x1b[0m
+  Every agent's state, as one stream you can build on (lights, banners, webhooks):
+
+      vibe --events                  \x1b[90m# the current state, then one JSON line per change\x1b[0m
+      vibe --state                   \x1b[90m# one snapshot: idle, working, stuck or waiting\x1b[0m
+      vibe --statusline              \x1b[90m# one plain line for tmux or a prompt\x1b[0m
+
+  Events: started, waiting, resumed, stuck, recovered, finished, interrupted, ended, announced.
+  Recipes (tmux, Starship, voice, webhook, Home Assistant): https://kiril6.github.io/vibeaudio/
+
+\x1b[1mUNINSTALL:\x1b[0m
+  In this order, so no agent is left running a hook that points at nothing:
+
+      vibe --uninstall-hooks         \x1b[90m# 1. unwire every agent, and stop any player still running\x1b[0m
+      npm rm -g vibeaudio            \x1b[90m# 2. remove the CLI\x1b[0m
+      rm -rf ~/.vibeaudio            \x1b[90m# 3. optional: cached audio, saved settings, state\x1b[0m
+
 \x1b[1mENVIRONMENT:\x1b[0m
   VIBE_GENRE=<name>            Override the saved genre for this shell
   VIBE_VOLUME=<5-100>          Override the saved volume for this shell
   VIBE_CHIME_VOLUME=<5-100>    Override the saved chime volume for this shell
   VIBE_GRACE_MS=<ms>           Override the saved grace window, in ms
   VIBE_MUSIC=<on|off>          Override the saved music setting for this shell
+  VIBE_NOTIFY=<on|off>         Override the saved desktop-banner setting for this shell
   VIBE_SEED=<n>                Pin the arrangement instead of deriving it from the directory
   VIBE_DISABLE=1               Mute automatic playback without uninstalling anything
   VIBE_NO_UPDATE_CHECK=1       Never check npm for a newer version
+
+\x1b[1mNO SOUND?\x1b[0m
+  vibe --doctor                  \x1b[90m# checks the setup; each problem comes with its fix\x1b[0m
+  vibe --status                  \x1b[90m# shows whether you are muted, and what is installed\x1b[0m
+  vibe --unmute                  \x1b[90m# clears a mute\x1b[0m
+
+\x1b[1mMORE:\x1b[0m
+  Settings and state: ~/.vibeaudio
+  Docs: https://kiril6.github.io/vibeaudio/
+  Problems and ideas: https://github.com/kiril6/vibeaudio/issues
 `);
   printUpdateNotice();
 }
@@ -143,7 +178,11 @@ const VALUE_FLAGS = new Set([
   "--music",
   "--seed",
   "--tools",
-  "--event"
+  "--event",
+  "--announce",
+  "--outcome",
+  "--exit-code",
+  "--port"
 ]);
 
 function parseArgs(argv) {
@@ -198,6 +237,12 @@ function parseArgs(argv) {
   let followVolume = false;
   let plugin = false;
   let hookEvent = null;
+  let dashboardFlag = false;
+  let dashboardPort = null;
+  let noOpen = false;
+  let announceText = null;
+  let announceOutcome = null;
+  let announceExit = null;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -314,6 +359,45 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--announce" || arg === "--outcome" || arg === "--exit-code") {
+      const value = args[i + 1];
+      if (arg === "--announce") announceText = value;
+      else if (arg === "--outcome") {
+        announceOutcome = value.toLowerCase();
+        const known = require("./hooks").ANNOUNCE_OUTCOMES;
+        if (!known.includes(announceOutcome)) {
+          console.error(`\x1b[31m[vibeaudio] --outcome takes ${known.join(", ")}, not '${value}'.\x1b[0m`);
+          process.exit(1);
+        }
+      } else {
+        if (!/^-?\d+$/.test(value)) {
+          console.error(`\x1b[31m[vibeaudio] --exit-code takes a number, not '${value}'.\x1b[0m`);
+          process.exit(1);
+        }
+        announceExit = parseInt(value, 10);
+      }
+      i += 2;
+      continue;
+    }
+
+    if (arg === "--dashboard" || arg === "--no-open") {
+      if (arg === "--dashboard") dashboardFlag = true;
+      else noOpen = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--port") {
+      const n = Number(args[i + 1]);
+      if (!/^\d+$/.test(args[i + 1]) || n > 65535) {
+        console.error(`\x1b[31m[vibeaudio] --port takes a number from 0 to 65535, not '${args[i + 1]}'.\x1b[0m`);
+        process.exit(1);
+      }
+      dashboardPort = n;
+      i += 2;
+      continue;
+    }
+
     if (arg === "--statusline") {
       statuslineFlag = true;
       i += 1;
@@ -532,6 +616,8 @@ function parseArgs(argv) {
     followVolume,
     plugin,
     hookEvent,
+    dashboard: dashboardFlag ? { port: dashboardPort, open: !noOpen } : null,
+    announce: { text: announceText, outcome: announceOutcome, exitCode: announceExit },
     dryRun,
     tools,
     typed,
@@ -659,6 +745,7 @@ function installHookTargets(ids, genre, volume, reactive, dryRun = false, typed
   const live = ids.filter((id) => hooks.TARGETS[id].liveReload !== false).map((id) => hooks.TARGETS[id].name);
   if (live.length) console.log(`  ${live.join(", ")}: takes effect on your next prompt - no restart needed.`);
   console.log(`  \x1b[90mChange the sound any time with: vibe --genre <name> --volume <n> — no reinstall.\x1b[0m`);
+  console.log(`  \x1b[90mCheck it with vibe --status · quiet for a call: vibe --mute · everything else: vibe --help\x1b[0m`);
   if (ids.length > 1) {
     console.log(`  \x1b[90mOne player is shared: whichever agent you prompt last owns the music.\x1b[0m`);
   }
@@ -1492,6 +1579,17 @@ function windowsCommandNeedsShell(command) {
   return !/[\\/]/.test(command);
 }
 
+function openBrowser(url) {
+  const { spawn } = require("child_process");
+  const [cmd, args] =
+    process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref(); // no browser to open is not an error
+  } catch (e) { /* same */ }
+}
+
 function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false, music = true) {
   const player = new AudioPlayer();
   const hookDriven = hooksAlreadyCover(cmdArgs);
@@ -1590,6 +1688,42 @@ function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRA
   process.on("SIGTERM", () => relaySignal("SIGTERM"));
 }
 
+/**
+ * Acts on what the menu returned, and says whether to launch the tool.
+ *
+ * Choosing hooks is setup: it installs them and stops. Nothing is started, so
+ * someone running several agents can set one up now and open it when they
+ * like - the music plays from their first prompt either way. Only "just launch
+ * it" and "this session only" go on to start the tool. A failed install is an
+ * error with a non-zero exit, not a launch without the hooks that were asked for.
+ */
+function applyMenuSelection(selection, volume) {
+  if (!selection.installHooks) return true;
+  const hooks = require("./hooks");
+  try {
+    installHookTargets([selection.hookTarget], selection.genre, volume, selection.reactive, false,
+      { genre: selection.genre, volume });
+  } catch (err) {
+    console.error(`\x1b[31m[vibeaudio] ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+  const saved = loadConfig();
+  // Everything VibeAudio is hooked into on this machine, not just this run's
+  // pick: with several agents, "which ones are set up?" is the question, and
+  // which one to open first is the user's call.
+  const hooked = Object.entries(hooks.TARGETS).filter(([id]) => hooks.userHooksInstalled(null, id));
+  const names = hooked.map(([, t]) => t.name).join(", ");
+  const cmds = hooked.map(([, t]) => t.cmd).join(", ");
+  console.log(
+    `\n\x1b[32m✔ VibeAudio v${pkg.version} is hooked into: ${names} (${saved.genre} @ ${saved.volume}%).\x1b[0m ` +
+    `Nothing was started: open ${hooked.length > 1 ? "any of them" : "it"} whenever you like (\x1b[1m${cmds}\x1b[0m), and the music plays from your first prompt.\n` +
+    `  \x1b[90mMore agents? Run vibe again for each, or vibe --install-hooks to set up every one it finds.\x1b[0m\n` +
+    `  \x1b[90mStay current: run npm i -g ${pkg.name} now and then (hooks keep working); vibe --status tells you when a newer version is out.\x1b[0m\n`
+  );
+  printUpdateNotice();
+  return false;
+}
+
 async function run() {
   const {
     genre,
@@ -1618,6 +1752,8 @@ async function run() {
     followVolume,
     plugin,
     hookEvent,
+    dashboard,
+    announce: announceReq,
     dryRun,
     tools,
     typed,
@@ -1643,6 +1779,25 @@ async function run() {
     }
   }
 
+  if (announceReq.text === null && (announceReq.outcome !== null || announceReq.exitCode !== null)) {
+    console.error("\x1b[31m[vibeaudio] --outcome and --exit-code go with --announce <text>.\x1b[0m");
+    process.exit(1);
+  }
+  if (announceReq.text !== null) {
+    if (!announceReq.text.trim()) {
+      console.error("\x1b[31m[vibeaudio] --announce needs some text.\x1b[0m Run vibe --help for the options.");
+      process.exit(1);
+    }
+    if (announceReq.outcome !== null && announceReq.exitCode !== null) {
+      console.error("\x1b[31m[vibeaudio] Give --outcome or --exit-code, not both.\x1b[0m");
+      process.exit(1);
+    }
+    const outcome = announceReq.outcome || (announceReq.exitCode === null || announceReq.exitCode === 0 ? "success" : "failure");
+    // Exit 0 whatever happens: `cmd; vibe --announce ...` must not turn a pipeline red.
+    require("./hooks").announce(announceReq.text, { outcome, volume, chimeVolume, noChime, genre });
+    return;
+  }
+
   if (reactive) {
     console.error(
       "\x1b[33m[vibeaudio] --reactive only applies to --install-hooks; ignoring it here.\x1b[0m"
@@ -1714,6 +1869,21 @@ async function run() {
     return;
   }
 
+  if (dashboard) {
+    const { startDashboard } = require("./dashboard");
+    let server;
+    try {
+      server = await startDashboard({ port: dashboard.port });
+    } catch (e) {
+      console.error(`\x1b[31m[vibeaudio] Could not start the dashboard: ${e.code === "EADDRINUSE" ? `port ${dashboard.port} is in use` : e.message}.\x1b[0m`);
+      process.exit(1);
+    }
+    const url = `http://127.0.0.1:${server.address().port}/`;
+    console.log(`\x1b[1mVibeAudio dashboard\x1b[0m  ${url}  \x1b[90m(read-only, this machine only; Ctrl+C to stop)\x1b[0m`);
+    if (dashboard.open) openBrowser(url);
+    return; // the listening server keeps the process alive
+  }
+
   if (followEvents) {
     process.stdout.on("error", () => process.exit(0)); // `vibe --events | head` closing the pipe is not an error.
     require("./hooks").followEvents();
@@ -1770,18 +1940,7 @@ async function run() {
     }
 
     const chosenVol = selection.volume !== undefined ? selection.volume : volume;
-
-    if (selection.installHooks) {
-      // The install can refuse (npx checkout) or abort (malformed settings).
-      // Either way, say so and still launch the tool the user asked for -
-      // they came here to start an agent, not to configure one.
-      try {
-        installHookTargets([selection.hookTarget], selection.genre, chosenVol, selection.reactive, false,
-          { genre: selection.genre, volume: chosenVol });
-      } catch (err) {
-        console.error(`\x1b[31m[vibeaudio] ${err.message}\x1b[0m`);
-      }
-    }
+    if (!applyMenuSelection(selection, chosenVol)) return;
 
     return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud, music);
   }
@@ -1793,6 +1952,7 @@ module.exports = {
   run,
   parseArgs,
   hooksAlreadyCover,
+  applyMenuSelection,
   previewAudioFile,
   windowsCommandNeedsShell
 };

package/src/dashboard.js

@@ -0,0 +1,187 @@
+"use strict";
+
+/**
+ * `vibe --dashboard`: a read-only local page showing what every agent is doing.
+ * Built on what already exists: the page is fed by followEvents() (the same
+ * follower behind `vibe --events`) over Server-Sent Events, so there is one
+ * source of truth and nothing here reads session files itself.
+ *
+ * Local by construction: bound to 127.0.0.1, a Host check against the bound
+ * address (so a page on the open web cannot reach it through DNS rebinding),
+ * no CORS headers, and a CSP that allows exactly this page's one script. It
+ * only ever answers GET, so there is nothing a cross-site request could do.
+ * Controls (mute, stop) are a separate decision, because they would need CSRF
+ * protection first.
+ */
+
+const http = require("http");
+const crypto = require("crypto");
+const hooks = require("./hooks");
+
+const DEFAULT_PORT = 4747;
+const MAX_CLIENTS = 20;
+const HEARTBEAT_MS = 15000;
+const BACKLOG_LINES = 25;
+
+const STYLE = `
+:root{color-scheme:light dark;--bg:#f6f7f9;--card:#fff;--ink:#14171c;--dim:#667085;--line:#e3e6ea;--work:#1a7f4b;--wait:#b45309;--stuck:#c0262d;--idle:#98a2b3}
+@media(prefers-color-scheme:dark){:root{--bg:#0e1116;--card:#171b22;--ink:#e8ebf0;--dim:#8b95a5;--line:#262c36;--work:#4cc38a;--wait:#f5a524;--stuck:#ff6b72;--idle:#667085}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:860px;margin:0 auto;padding:24px 16px 48px}
+header{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap;margin-bottom:20px}
+h1{font-size:20px;margin:0}h2{font-size:13px;letter-spacing:.06em;text-transform:uppercase;color:var(--dim);margin:28px 0 8px}
+#status{font-weight:600}#conn{margin-left:auto;font-size:13px;color:var(--dim)}
+.card{background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+.row{display:grid;grid-template-columns:132px 1fr auto;gap:12px;align-items:center;padding:12px 14px;border-top:1px solid var(--line)}
+.row:first-child{border-top:0}.state{font-weight:600}.proj{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.path{color:var(--dim);font-size:12px;display:block;overflow:hidden;text-overflow:ellipsis}.time{color:var(--dim);font-variant-numeric:tabular-nums;font-size:13px}
+.working .state{color:var(--work)}.waiting .state{color:var(--wait)}.stuck .state{color:var(--stuck)}
+.waiting{background:color-mix(in srgb,var(--wait) 9%,transparent)}.stuck{background:color-mix(in srgb,var(--stuck) 9%,transparent)}
+.empty{padding:20px 14px;color:var(--dim)}
+li{list-style:none;display:grid;grid-template-columns:72px 96px 1fr;gap:10px;padding:7px 14px;border-top:1px solid var(--line);font-size:13px}
+ul{margin:0;padding:0}li:first-child{border-top:0}li .t{color:var(--dim);font-variant-numeric:tabular-nums}li.bad{color:var(--stuck)}li.attn{color:var(--wait)}
+@media(max-width:520px){.row{grid-template-columns:80px 1fr}.row .time{grid-column:2}li{grid-template-columns:60px 1fr}li .e{grid-column:2}li .d{grid-column:2}}
+`;
+
+const SCRIPT = `
+const $ = (id) => document.getElementById(id);
+const RANK = { waiting: 0, stuck: 1, working: 2 };
+const seen = new Map(); // session -> { state, at }: when this page first saw it in that state
+let rows = [];
+const base = (p) => String(p || "").replace(/[\\\\/]+$/, "").split(/[\\\\/]/).pop() || "a session";
+const dur = (ms) => { const s = Math.max(0, Math.floor(ms / 1000)); return s < 60 ? s + "s" : s < 3600 ? Math.floor(s / 60) + "m " + (s % 60) + "s" : Math.floor(s / 3600) + "h " + Math.floor(s % 3600 / 60) + "m"; };
+const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined) e.textContent = text; return e; };
+
+function renderState(st) {
+  const now = Date.now();
+  $("status").textContent = st.status;
+  document.title = st.status === "idle" ? "VibeAudio" : st.status + " - VibeAudio";
+  rows = st.sessions.slice().sort((a, b) => RANK[a.state] - RANK[b.state]).map((s) => {
+    const prev = seen.get(s.session);
+    const at = prev && prev.state === s.state ? prev.at : (prev ? now : ((s.state === "waiting" && s.waitingSince) || s.since || now));
+    seen.set(s.session, { state: s.state, at });
+    return { ...s, at };
+  });
+  for (const id of seen.keys()) if (!st.sessions.some((s) => s.session === id)) seen.delete(id);
+  paint();
+}
+
+function paint() {
+  const box = $("sessions");
+  box.replaceChildren();
+  if (!rows.length) { box.append(el("div", "empty", "Nothing is running. Start a turn in any agent with VibeAudio hooks and it appears here.")); return; }
+  for (const s of rows) {
+    const row = el("div", "row " + s.state);
+    row.append(el("span", "state", s.state + (s.tool ? " (" + s.tool + ")" : "")));
+    const name = el("span", "proj", base(s.project));
+    if (s.project) name.append(el("span", "path", s.project));
+    row.append(name, el("span", "time", dur(Date.now() - s.at)));
+    box.append(row);
+  }
+}
+
+function addEvent(e) {
+  const li = el("li", e.outcome === "failure" || e.event === "stuck" ? "bad" : e.event === "waiting" || (e.event === "announced" && e.outcome === "attention") ? "attn" : "");
+  li.append(el("span", "t", new Date(e.at).toLocaleTimeString([], { hour12: false })), el("span", "e", e.event), el("span", "d", [e.text || base(e.project), e.tool, e.outcome].filter(Boolean).join(" · ")));
+  const list = $("feed");
+  list.prepend(li);
+  while (list.children.length > 60) list.lastChild.remove();
+}
+
+const es = new EventSource("/events");
+es.addEventListener("state", (m) => renderState(JSON.parse(m.data)));
+es.addEventListener("event", (m) => addEvent(JSON.parse(m.data)));
+es.addEventListener("backlog", (m) => JSON.parse(m.data).forEach(addEvent));
+es.onopen = () => { $("conn").textContent = "live"; };
+es.onerror = () => { $("conn").textContent = "reconnecting…"; };
+setInterval(paint, 1000);
+`;
+
+const BODY = `<main>
+<header><h1>VibeAudio</h1><span id="status" aria-live="polite">idle</span><span id="conn">connecting…</span></header>
+<h2>Sessions</h2><div class="card" id="sessions"></div>
+<h2>Recent events</h2><div class="card"><ul id="feed"></ul></div>
+</main>`;
+
+const PAGE = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>VibeAudio</title><style>${STYLE}</style></head><body>${BODY}<script>${SCRIPT}</script></body></html>`;
+
+// The page's one script is allowed by hash, so no other script, inline or not, can run in it.
+const SCRIPT_HASH = crypto.createHash("sha256").update(SCRIPT).digest("base64");
+const CSP = `default-src 'none'; script-src 'sha256-${SCRIPT_HASH}'; style-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;
+const HEADERS = { "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Content-Security-Policy": CSP, "Referrer-Policy": "no-referrer" };
+
+/**
+ * Creates the server (not yet listening). `close()` also ends the event
+ * streams, which would otherwise keep it open forever.
+ */
+function createDashboard() {
+  const clients = new Set();
+  const server = http.createServer((req, res) => {
+    // DNS rebinding: a hostile page can point its own name at 127.0.0.1, but the
+    // browser then sends that name as Host. Only our own address is accepted.
+    const port = server.address() && server.address().port;
+    const host = String(req.headers.host || "").toLowerCase();
+    if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+      res.writeHead(403, { ...HEADERS, "Content-Type": "text/plain" }).end("Forbidden\n");
+      return;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405, { ...HEADERS, Allow: "GET, HEAD", "Content-Type": "text/plain" }).end("Read-only\n");
+      return;
+    }
+    const url = (req.url || "").split("?")[0];
+    if (url === "/") {
+      res.writeHead(200, { ...HEADERS, "Content-Type": "text/html; charset=utf-8" });
+      res.end(req.method === "HEAD" ? undefined : PAGE);
+      return;
+    }
+    if (url === "/events" && req.method === "GET") {
+      if (clients.size >= MAX_CLIENTS) {
+        res.writeHead(503, { ...HEADERS, "Content-Type": "text/plain" }).end("Too many viewers\n");
+        return;
+      }
+      res.writeHead(200, { ...HEADERS, "Content-Type": "text/event-stream", Connection: "keep-alive" });
+      const send = (name, data) => res.write(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+      send("backlog", hooks.recentEvents(BACKLOG_LINES));
+      const follower = hooks.followEvents((chunk) => {
+        let line;
+        try { line = JSON.parse(chunk); } catch (e) { return; }
+        if (line.event === "state") return send("state", line);
+        send("event", line);
+        send("state", hooks.agentState()); // an event says what changed; the page wants the list
+      });
+      const beat = setInterval(() => res.write(": ping\n\n"), HEARTBEAT_MS);
+      const client = { res, stop: () => { clearInterval(follower); clearInterval(beat); clients.delete(client); } };
+      clients.add(client);
+      req.on("close", client.stop);
+      return;
+    }
+    res.writeHead(404, { ...HEADERS, "Content-Type": "text/plain" }).end("Not found\n");
+  });
+  const close = server.close.bind(server);
+  server.close = (cb) => {
+    for (const c of [...clients]) { c.stop(); c.res.end(); }
+    return close(cb);
+  };
+  return server;
+}
+
+/**
+ * Listens on 127.0.0.1 only. An explicit port is taken or it is an error; the
+ * default port falls back to a free one, so a second dashboard still starts.
+ */
+function startDashboard({ port = null } = {}) {
+  const server = createDashboard();
+  return new Promise((resolve, reject) => {
+    const listen = (p) => {
+      server.once("error", (e) => {
+        if (e.code === "EADDRINUSE" && port === null && p !== 0) return listen(0);
+        reject(e);
+      });
+      server.listen(p, "127.0.0.1", () => resolve(server));
+    };
+    listen(port === null ? DEFAULT_PORT : port);
+  });
+}
+
+module.exports = { createDashboard, startDashboard, DEFAULT_PORT, CSP };

package/src/hooks.js

@@ -189,6 +189,32 @@ function codexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
+/**
+ * The three further agents that move with an env var, each read from the
+ * agent's own code; empty is unset for all of them.
+ * Gemini CLI: `GEMINI_CLI_HOME` replaces the *home*, so settings live in
+ * `<it>/.gemini` (homedir() in core, 0.62.0 bundle); used as written, no `~`.
+ * Qwen Code: `QWEN_HOME` *is* the `.qwen` directory, with `~` expanded and the
+ * rest path.resolve()d (Storage.getGlobalQwenDir(), 0.25.0 bundle).
+ * Grok: `GROK_HOME` *is* the `.grok` directory (grok_home(); the npm launcher
+ * and postinstall.js of @xai-official/grok 1.0.46 write config.toml there).
+ * Cursor and Windsurf: no override found, and neither is open to read.
+ */
+function geminiDir() {
+  return path.join(process.env.GEMINI_CLI_HOME || os.homedir(), ".gemini");
+}
+
+function qwenHome() {
+  const dir = process.env.QWEN_HOME;
+  if (!dir) return path.join(os.homedir(), ".qwen");
+  const rest = /^~(?:[\\/]|$)/.test(dir) ? dir.slice(2).split(/[\\/]+/).filter(Boolean) : null;
+  return path.resolve(rest ? path.join(os.homedir(), ...rest) : dir);
+}
+
+function grokHome() {
+  return process.env.GROK_HOME || path.join(os.homedir(), ".grok");
+}
+
 const TARGETS = {
   claude: {
     name: "Claude Code",
@@ -256,10 +282,10 @@ const TARGETS = {
     // Grok reads every *.json in this directory, so we get a file of our own
     // rather than merging into someone else's - which also makes uninstall a
     // delete instead of an edit. `dedicated` says so.
-    file: () => path.join(os.homedir(), ".grok", "hooks", "vibeaudio.json"),
+    file: () => path.join(grokHome(), "hooks", "vibeaudio.json"),
     dedicated: true,
     // Directory, not file: detection can't use dirname() like the others.
-    configDir: () => path.join(os.homedir(), ".grok"),
+    configDir: () => grokHome(),
     events: { start: "UserPromptSubmit", stop: "Stop", tool: "PreToolUse" },
     entry: (command) => ({ hooks: [{ type: "command", command, timeout: 5 }] }),
     commands: (entry) => (entry.hooks || []).map((h) => h.command),
@@ -268,7 +294,7 @@ const TARGETS = {
   gemini: {
     name: "Gemini CLI",
     cmd: "gemini",
-    file: () => path.join(os.homedir(), ".gemini", "settings.json"),
+    file: () => path.join(geminiDir(), "settings.json"),
     // Verified against gemini-cli v0.59.0's source (hooks/types.ts,
     // settingsSchema.ts) - the Gemini CLI available to test against predated
     // hooks, so there was no binary to run. Hooks are on by default and
@@ -321,7 +347,7 @@ const TARGETS = {
   qwen: {
     name: "Qwen Code",
     cmd: "qwen",
-    file: () => path.join(os.homedir(), ".qwen", "settings.json"),
+    file: () => path.join(qwenHome(), "settings.json"),
     // Verified against qwen-code v0.23.3's source (hooks/types.ts): Claude
     // Code's event set, including a PermissionRequest raised when the dialog
     // is displayed, with tool_name. Timeouts are milliseconds.
@@ -535,10 +561,13 @@ function daemonArgv(pid) {
   try {
     return execFileSync("ps", ["-p", String(pid), "-o", "args="], {
       encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
+      stdio: ["ignore", "pipe", "ignore"],
+      // Run on every prompt: a ps that never answers must not hold the hook.
+      timeout: 3000,
+      killSignal: "SIGKILL"
     });
   } catch (e) {
-    return null; // No such process, or ps unavailable.
+    return null; // No such process, ps unavailable, or it did not answer in time.
   }
 }
 
@@ -754,7 +783,8 @@ function agentState(sessions = listSessions()) {
     project: s.project || null,
     state: sessionState(s),
     since: s.started || null,
-    ...(s.waiting ? { tool: s.waiting } : {})
+    ...(s.waiting ? { tool: s.waiting } : {}),
+    ...(s.waiting != null && s.waitStart ? { waitingSince: s.waitStart } : {})
   }));
   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 };
@@ -835,6 +865,17 @@ function followEvents(write = (s) => process.stdout.write(s), pollMs = 250) {
   }, pollMs);
 }
 
+/** The last `n` events in the log, oldest first; [] when there is none yet. */
+function recentEvents(n = 25) {
+  try {
+    return fs.readFileSync(EVENTS_FILE, "utf8").split("\n").filter(Boolean).slice(-n).flatMap((l) => {
+      try { return [JSON.parse(l)]; } catch (e) { return []; } // a torn line is not worth losing the rest
+    });
+  } catch (e) {
+    return [];
+  }
+}
+
 // 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";
@@ -1100,9 +1141,9 @@ function notifyCommand(platform, title, body) {
 // Detached and unref'd: the agent waits on this hook, and a missing
 // osascript/notify-send (a Linux box with no notification daemon) must be
 // invisible rather than an error in someone's agent.
-function notify(raw, message) {
+function banner(body) {
   if (!notifyEnabled() || playbackDisabled()) return false; // a mute means quiet, banners included
-  const command = notifyCommand(process.platform, "VibeAudio", `${sessionLabel(parsePayload(raw))}: ${message}`);
+  const command = notifyCommand(process.platform, "VibeAudio", body);
   if (!command) return false;
   try {
     const child = spawn(command.cmd, command.args, { detached: true, stdio: "ignore" });
@@ -1114,6 +1155,50 @@ function notify(raw, message) {
   }
 }
 
+function notify(raw, message) {
+  return banner(`${sessionLabel(parsePayload(raw))}: ${message}`);
+}
+
+const ANNOUNCE_FILE = path.join(STATE_DIR, "announce.json");
+const ANNOUNCE_MAX_CHARS = 200;
+const ANNOUNCE_REPEAT_MS = 5000;
+const ANNOUNCE_OUTCOMES = ["success", "failure", "attention"];
+
+/**
+ * `vibe --announce <text>`: VibeAudio's signals for something that is not an
+ * agent turn (a CI run, a deploy, a script). A chime for the outcome, the
+ * `--notify` banner, and an `announced` event, so a light watching `--events`
+ * reacts too. Never starts or stops music and never touches a session.
+ *
+ * The text is shown in a banner, so control characters go and the length is
+ * capped; it only ever travels as argv. A repeat of the same text within a few
+ * seconds is dropped whole, so a script in a loop cannot machine-gun the
+ * speakers. Mute silences the chime and banner; the event is still written,
+ * like every event.
+ *
+ * Returns false when it was a repeat, true otherwise; never throws.
+ */
+function announce(text, { outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre } = {}) {
+  try {
+    const clean = String(text).replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, ANNOUNCE_MAX_CHARS);
+    const now = Date.now();
+    try {
+      const last = JSON.parse(fs.readFileSync(ANNOUNCE_FILE, "utf8"));
+      if (last.text === clean && now - last.at < ANNOUNCE_REPEAT_MS) return false;
+    } catch (e) { /* first one, or an unreadable file: nothing to compare */ }
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(ANNOUNCE_FILE, JSON.stringify({ text: clean, at: now }));
+
+    emitEvent("announced", null, null, { source: "cli", text: clean, outcome });
+    banner(`${clean}${outcome === "failure" ? " (failed)" : outcome === "attention" ? " (needs you)" : ""}`);
+    // Detached: a pipeline should not wait out the chime.
+    if (!noChime) new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre, detach: true });
+    return true;
+  } catch (e) {
+    return true; // a notifier must never fail the script that called it
+  }
+}
+
 function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
   const id = sessionId(payloadSession(parsePayload(raw)));
   // A turn that ends while paused for the user - a denied tool that nothing
@@ -1582,6 +1667,14 @@ module.exports = {
   shellQuote,
   claudeConfigDir,
   codexHome,
+  geminiDir,
+  qwenHome,
+  grokHome,
+  announce,
+  recentEvents,
+  emitEvent,
+  ANNOUNCE_OUTCOMES,
+  ANNOUNCE_MAX_CHARS,
   expectedEvents,
   PLUGIN_FILES,
   PLUGIN_AGENTS,

package/src/interactive.js

@@ -11,7 +11,7 @@ const LOOKUP_CMD = process.platform === "win32" ? "where" : "which";
 
 function isInstalled(cmd) {
   // An argument vector, not a command string: nothing in `cmd` reaches a shell.
-  return spawnSync(LOOKUP_CMD, [cmd], { stdio: "ignore" }).status === 0;
+  return spawnSync(LOOKUP_CMD, [cmd], { stdio: "ignore", timeout: 3000, killSignal: "SIGKILL" }).status === 0;
 }
 
 // Convenience only - the wrapper runs any command, and "Custom command..."
@@ -263,7 +263,7 @@ const DELIVERY_FRESH = [
   {
     id: "hooks",
     name: "Agent hooks",
-    desc: "Music follows the agent's thinking. Set once, no wrapper needed"
+    desc: "Music follows the agent's thinking. Installs, then returns to your shell: nothing starts"
   },
   {
     id: "wrapper",
@@ -285,7 +285,7 @@ const DELIVERY_INSTALLED = [
   {
     id: "hooks",
     name: "Reconfigure the hooks",
-    desc: "Pick a new genre, volume or reactive setting"
+    desc: "Pick a new genre, volume or reactive setting. Nothing starts"
   }
 ];
 

package/src/player.js

@@ -8,6 +8,9 @@ const path = require("path");
 const os = require("os");
 const { spawn, spawnSync } = require("child_process");
 
+// The most a `which`/`ps` lookup may take; they answer in milliseconds, and a hook waits on them.
+const LOOKUP_TIMEOUT_MS = 3000;
+
 const { generateLofiLoop } = require("./synth/lofi");
 const { generateSynthwaveLoop } = require("./synth/synthwave");
 const { generateChiptuneLoop } = require("./synth/chiptune");
@@ -146,7 +149,8 @@ function detectPlayer() {
   }
 
   cachedPlayer = PLAYER_CANDIDATES.find(
-    (c) => spawnSync("which", [c.cmd], { stdio: "ignore" }).status === 0
+    // A lookup that never answers is "not found", not a hook that never returns.
+    (c) => spawnSync("which", [c.cmd], { stdio: "ignore", timeout: LOOKUP_TIMEOUT_MS, killSignal: "SIGKILL" }).status === 0
   ) || null;
 
   return cachedPlayer;