vibeaudio 0.17.0 → 0.18.0

package/README.md

@@ -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>
@@ -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,46 @@ 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 (it has no `event` field), 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.
+
+*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 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 +785,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.18.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)
@@ -143,7 +150,11 @@ const VALUE_FLAGS = new Set([
   "--music",
   "--seed",
   "--tools",
-  "--event"
+  "--event",
+  "--announce",
+  "--outcome",
+  "--exit-code",
+  "--port"
 ]);
 
 function parseArgs(argv) {
@@ -198,6 +209,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 +331,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 +588,8 @@ function parseArgs(argv) {
     followVolume,
     plugin,
     hookEvent,
+    dashboard: dashboardFlag ? { port: dashboardPort, open: !noOpen } : null,
+    announce: { text: announceText, outcome: announceOutcome, exitCode: announceExit },
     dryRun,
     tools,
     typed,
@@ -1492,6 +1550,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);
@@ -1618,6 +1687,8 @@ async function run() {
     followVolume,
     plugin,
     hookEvent,
+    dashboard,
+    announce: announceReq,
     dryRun,
     tools,
     typed,
@@ -1643,6 +1714,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 +1804,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();

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..."

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;