vibeaudio 0.14.1 → 0.15.0

package/README.md

@@ -1,10 +1,14 @@
 # 🎧 VibeAudio
 
+<p align="center">
+  <img src="docs/og.png?v=2" alt="VibeAudio — Focus music while your AI codes" width="720">
+</p>
+
 [![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/vibeaudio)](https://www.npmjs.com/package/vibeaudio) [![downloads](https://img.shields.io/npm/d18m/vibeaudio?label=downloads)](https://npm-stat.com/charts.html?package=vibeaudio) [![downloads/month](https://img.shields.io/npm/dm/vibeaudio)](https://npm-stat.com/charts.html?package=vibeaudio)
 
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
-> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Aider — and any terminal command.
+> Works with Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf, Antigravity, Aider — and any terminal command.
 
 **[Install](#-install)** · **[Agent hooks](#-agent-hooks-no-wrapper-needed)** · **[Genres](#-music-genres)** · **[Flags](#-options--flags)** · **[Troubleshooting](#-troubleshooting)** · **[Uninstall](#-uninstall)**
 
@@ -31,7 +35,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 
 **How it behaves:**
 
-* 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no `node-gyp`.
+* 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no install scripts, no `node-gyp`.
 * 🍃 **Light on battery.** Each loop is rendered once and cached. While music plays, your OS's own audio player does the work. With hooks, nothing of VibeAudio's keeps running between turns.
 * 🎼 **A different arrangement per project.** Your working directory seeds the progression, bass line and melody, so each repo has its own sound and keeps it.
 * 📈 **Escalating layers.** Tier 1 (0–15s) gentle intro → Tier 2 (15–45s) main groove → Tier 3 (45s+) deep focus. You can hear how deep into the task the agent is.
@@ -41,7 +45,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 * 🔔 **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.
+* 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code, Windsurf and Antigravity**; MCP for **Claude Desktop**; the wrapper (`vibe <command>`) for anything else.
 
 <details>
 <summary><b>And the quieter four</b> — silence on fast commands, several sessions at once, exit codes, the HUD</summary>
@@ -49,7 +53,7 @@ It is built as **calm technology**, in the sense of Mark Weiser and John Seely B
 * 🛡️ **A grace window.** Fast commands stay 100% silent — music starts only past 1.5s (`--grace`).
 * 🪟 **Several sessions, one soundtrack.** Run as many terminals of the same agent as you like: the music plays while *any* of them is working, and each finishes with its own chime. One session ending, pausing for a permission dialog or being interrupted never cuts off another that's still going.
 * 🧮 **Honest exit codes.** Your command's status passes straight through (`130` on `Ctrl+C`), so `vibe claude && next-step` behaves exactly as it would without the wrapper.
-* 🌊 **Terminal title HUD.** A live ASCII wave and elapsed timer in the window title, where it can't corrupt a full-screen TUI.
+* 🌊 **Terminal title HUD.** A live ASCII wave and elapsed timer in the window title (`[ ♫ ▃▅▆▇█▇▆▃ lofi (0:24) ]`), where it can't corrupt a full-screen TUI.
 
 </details>
 
@@ -237,7 +241,7 @@ Adding an entry to the launcher is one line in [`src/interactive.js`](src/intera
 
 ## 🪝 Agent Hooks (no wrapper needed)
 
-> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code and Windsurf.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-antigravity-via-mcp) instead.
+> **`--install-hooks` supports Claude Code, Codex, Cursor, Grok, Gemini CLI, GitHub Copilot CLI, Qwen Code, Windsurf and Antigravity.** Everything else uses the [wrapper or MCP](#-everything-else-claude-desktop-vs-code-via-mcp) instead.
 
 Wrapping (`vibe claude`) infers "the AI is thinking" from how long the process runs. Hooks know for certain — so music starts the moment you submit a prompt and stops the moment the agent finishes, with no grace-window guessing and no aliases.
 
@@ -250,12 +254,12 @@ vibe --genre jazz --volume 25 --install-hooks    # install, and save these as yo
 vibe --install-hooks --dry-run                   # show what would change, write nothing
 ```
 
-**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
+**It auto-detects.** With no `--tools`, VibeAudio wires up each supported agent it finds on your machine — one counts as present when its config directory exists or its CLI is on your `PATH`. `--tools claude,codex,cursor,grok,gemini,copilot,qwen,windsurf,antigravity` overrides that. Add `--dry-run` to see, per event, what would be added or changed in each file before anything is written.
 
 That's it — run your agent normally, with no `vibe` prefix.
 
 <details>
-<summary><b>Which file and which events, per agent</b> — eight dialects, all written for you</summary>
+<summary><b>Which file and which events, per agent</b> — nine dialects, all written for you</summary>
 
 Each tool spells its events its own way, and VibeAudio writes whichever dialect the file expects:
 
@@ -269,6 +273,7 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 | **Copilot CLI** | `~/.copilot/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Qwen Code** | `~/.qwen/settings.json` | `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)) |
 
 Where an agent reports more than start and stop, VibeAudio listens for that too — and only where the event was confirmed against the tool itself:
 
@@ -279,12 +284,13 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Gemini CLI** | `Notification` (tool permission) | `AfterTool` | — | `SessionEnd` |
 | **Copilot CLI** | `Notification` (permission prompt) | `PostToolUse`, `PostToolUseFailure` | — | `SessionEnd` |
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
+| **Antigravity** | — | — | `Stop` ending in an error or the step limit | — |
 | **Cursor, Grok, Windsurf** | — | — | — | — |
 
 </details>
 
 <details>
-<summary><b>Six things that differ per agent</b> — only the first one needs anything from you</summary>
+<summary><b>Seven things that differ per agent</b> — only the first one needs anything from you</summary>
 
 
 | | |
@@ -292,7 +298,8 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Five agents tell you when they're waiting on you** | When a permission dialog opens the music stops rather than sounding busy while the agent is stuck on you, and it resumes once the thing you answered has run. Claude Code covers the terminal, desktop app and IDEs alike, plus MCP servers asking for input. Copilot CLI's own `PermissionRequest` fires before *every* permission check — dialog or not — so VibeAudio listens for its permission-prompt notification instead. Cursor and Grok have no such event that's been verified, so they keep playing through a prompt. |
 | **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. |
+| **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. |
 | **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`. |
@@ -319,9 +326,9 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 </details>
 
-> **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.
+> **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, Windsurf or Antigravity 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` (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).)
+> **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-vs-code-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.
 
@@ -352,11 +359,16 @@ Codex asks you to approve the plugin's hooks once, as it does for any hook. Upda
 
 The plugin needs Node 18+ on your `PATH` (the hooks run `node`). In Claude Code it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
 
+<details>
+<summary><b>Plugin details & coexistence with npm</b> — settings file, coexistence, and limitations</summary>
+
 - **Settings are the same file.** `vibe --genre jazz` and the rest work as always, but the `vibe` command comes from `npm i -g vibeaudio`; the plugin alone puts nothing on your `PATH`. Use `/vibeaudio:vibe genre jazz` instead.
 - **Both at once is safe.** If `--install-hooks` has also been run, the plugin's hooks step aside and the installed ones play, so there's no double chime. Remove the installed hooks first if you want the plugin to own it.
 - **Claude Code and Codex.** Cursor, Gemini and the others still use `vibe --install-hooks`. Copilot CLI and Qwen Code can load the same plugin and it carries their events, but neither has been run with it yet.
 - **Not reactive.** `--reactive` is an `--install-hooks` option; the plugin doesn't carry it.
 
+</details>
+
 ### `/vibe` inside Claude Code
 
 Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`, or under `$CLAUDE_CONFIG_DIR`), so you can control the music without leaving the session:
@@ -419,8 +431,13 @@ Hooks log each finished turn — which project, how long, how it ended, and how
                     32s with a chime  1m 50s without (muted or --no-chime)
 ```
 
+<details>
+<summary><b>How the report metrics & return times are calculated</b></summary>
+
 plus where the time went by project and, for windows up to two weeks, by day. "You waited" is the agent's own working time; the time it spent blocked on you is shown separately, because they are different problems. "Back to it" is the other direction: how long a finished turn sat before your next prompt in the same session — gaps over 30 minutes count as breaks and are left out. Once both sides have five turns, it is split by whether a chime announced the turn, so you can see what the chime is worth to you. The log stays on your machine, never leaves it, is capped at about 1 MB, and `VIBE_NO_HISTORY=1` turns it off. Only hook-driven turns are logged — a command wrapped as `vibe <command>` is not, since its lifetime isn't the same thing as an agent's working time.
 
+</details>
+
 ### The chime is in the music's key
 
 The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
@@ -429,9 +446,14 @@ The success chime is the tonic chord of whatever key your genre sits in — C ma
 
 The worst stretch of agent work is twenty minutes of the same thing failing while the music says all is well. So when **4 of a session's last 8 tool calls fail**, a soft heartbeat — two low beats about once a second, on the tonic of your genre — joins the music at the next loop boundary, and leaves once enough calls succeed. With `--notify` on, you also get one banner when the session crosses the line ("api: looks stuck"), not one per failure.
 
+<details>
+<summary><b>How the stuck threshold was calibrated (4,497 turns analyzed)</b></summary>
+
 The threshold was picked against 4,497 real Claude Code turns (46,032 tool calls). It fires in about 1% of turns, at around minute 3, and those turns typically ran for another 3 minutes — time you could have spent stepping in. "3 in a row" was rejected because the usual loop has a successful edit between every failing test run. Each new prompt starts with a clean slate, and an interrupt (Esc) never counts as a failure.
 
-It needs the agent to report failed tool calls, which **Claude Code, Copilot CLI and Qwen Code** do (`PostToolUseFailure`). Codex, Cursor, Gemini, Grok and Windsurf don't, so for them the music never adds the heartbeat.
+It needs the agent to report failed tool calls, which **Claude Code, Copilot CLI and Qwen Code** do (`PostToolUseFailure`). Codex, Cursor, Gemini, Grok, Windsurf and Antigravity don't (Antigravity reports a tool error, but not a failing command), so for them the music never adds the heartbeat.
+
+</details>
 
 ### Reactive mode (opt-in)
 
@@ -468,7 +490,7 @@ 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.
+The hard part of VibeAudio isn't the music. It's turning nine 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
@@ -483,23 +505,34 @@ Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiti
 {"v":1,"at":1791026130000,"event":"waiting","session":"…","project":"/work/api","tool":"Bash","status":"waiting"}
 ```
 
-Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field.
 
+#### 📟 Status Bar & Desktop Integrations
+
+**tmux status bar** — show overall agent state (`waiting`, `stuck`, `working`, or `idle`):
 ```bash
-# tmux: show the state in the status bar
 set -g status-right '#(vibe --state | jq -r .status)'
+```
 
-# macOS: say it out loud when any agent needs you
+**macOS speech alert** — announce out loud whenever an agent stops to ask for your input:
+```bash
 vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | while read p; do say "$(basename "$p") needs you"; done
 ```
 
+**Starship prompt** — custom indicator in `~/.config/starship.toml`:
+```toml
+[custom.vibe]
+command = "vibe --state | jq -r 'if .status != \"idle\" then \"🎧 \" + .status else \"\" end'"
+when = "command -v vibe >/dev/null"
+```
+
 The stream is a local file (`~/.vibeaudio/events.jsonl`, rotated at 256 KB), so it never leaves your machine. It keeps updating while you're muted, because a mute silences sound and a light isn't sound. The `v` field is the format version, and any breaking change will increment it.
 
-## 🖥️ Everything Else (Claude Desktop, Antigravity… via MCP)
+## 🖥️ 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) 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.
+**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.
 
-> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the eight agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
+> **This is weaker than hooks, by nature.** Hooks fire on an event; MCP tools are *model-invoked*, so the assistant has to decide to call `vibe_play` and remember `vibe_stop`. Expect the occasional silent turn — say "play some focus music while you work on this" if you want it reliably. **On any of the nine agents above, use [hooks](#-agent-hooks-no-wrapper-needed) instead.**
 
 Use an **absolute path**, not the bare `vibe` command: GUI apps launched from Finder don't inherit your shell's `PATH`, and version managers like `fnm` or `nvm` put `vibe` on a per-shell path that won't resolve. Print yours with:
 
@@ -525,7 +558,7 @@ Where the file lives:
 | Tool | Config file |
 | :--- | :--- |
 | **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| **Antigravity, VS Code, Zed, …** | that app's own MCP settings — same JSON shape |
+| **VS Code, Zed, …** | that app's own MCP settings — same JSON shape |
 
 Restart the app afterwards.
 
@@ -575,7 +608,7 @@ Playback stops automatically if the desktop client disconnects, and caps out aft
 
 ## 🎨 Music Genres
 
-VibeAudio includes **8 procedural music styles** synthesized entirely in code:
+VibeAudio includes **10 procedural sound styles** synthesized entirely in code:
 
 | Genre | Style | Vibe |
 | :--- | :--- | :--- |
@@ -591,7 +624,8 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 | `ocean` | 🌊 **Ocean** | Low surf on a slow swell that rises and drains — **no melody at all** |
 | `random` | 🎲 **Shuffle Mode** | Picks a surprise genre for the run — **never `drone`, `rain` or `ocean`** |
 
-**Aliases also work**, so you can ask for a genre the way you'd say it — `vibe --preview chill` is `lofi`:
+<details>
+<summary><b>Genre aliases</b> — you can ask for a genre the way you'd say it (<code>chill</code>, <code>retrowave</code>, <code>bossa</code>, <code>ambient</code>…)</summary>
 
 | Canonical | Also accepted |
 | :--- | :--- |
@@ -608,6 +642,8 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 
 Matching is case-insensitive, so `BOSSA` works too.
 
+</details>
+
 > **If any melody distracts you, use `drone`.** Every other genre plays something — notes, a progression, a bass line — and some people can't read while that happens. `drone` holds one low tone under a slow-breathing noise bed and never moves: closer to a fan or rainfall than to music. Tiers add weight rather than movement. If you want the fan-and-rainfall idea literally, `rain` and `ocean` are synthesized the same way (seeded noise, no recorded files): rain adds more droplets as the turn runs longer, ocean adds a second swell and then foam.
 >
 > **`piano` is the gentler version of that idea.** It still plays notes — two in eight seconds at tier 1 — but they're single struck tones with silence between them and nothing running underneath. Higher tiers fill the gaps rather than adding a groove. Try it before `drone` if you want *something* there.
@@ -681,7 +717,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--clear-cache` | Delete all cached audio, then exit | — |
 | `--mcp` | Run as an MCP stdio server for desktop apps | — |
 | `--install-hooks` | Wire music into your agent's hooks (no wrapper needed) | — |
-| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen,windsurf` | auto-detect |
+| `--tools <list>` | With `--install-hooks`: `claude,codex,cursor,grok,gemini,copilot,qwen,windsurf,antigravity` | auto-detect |
 | `--reactive` | With `--install-hooks`: intensity follows the tool in use | off |
 | `--dry-run` | With `--install-hooks`: show what would change in each file, write nothing | off |
 | `--uninstall-hooks` | Remove the hooks again, from every agent | — |
@@ -747,7 +783,9 @@ It shouldn't. The cache key includes a hash of the synth sources, so changing a
 vibe --clear-cache
 ```
 
-**Silent when the agent runs on another machine over SSH**
+<details>
+<summary><b>Silent when the agent runs on another machine over SSH (socket forwarding)</b></summary>
+
 Sound plays on the machine where the agent runs, and a remote server usually has no sound card — so VibeAudio finds no player and stays quiet. You can hear it locally by forwarding a PulseAudio socket through the SSH connection: the remote `paplay` sends the audio back over SSH to your own speakers.
 
 This needs a PulseAudio-compatible sound server on **your local machine**: a Linux desktop (PipeWire and PulseAudio both provide one) or Windows with WSLg. macOS has none built in, so this route doesn't apply there.
@@ -769,6 +807,8 @@ This needs a PulseAudio-compatible sound server on **your local machine**: a Lin
 
 If the second connection fails with the socket "already in use", an earlier session left it behind: `rm /tmp/vibe-pulse.sock` on the server, or set `StreamLocalBindUnlink yes` in the server's `sshd_config`. If `paplay` says access denied, your local PulseAudio requires its cookie — copy `~/.config/pulse/cookie` to the same path on the server.
 
+</details>
+
 **Volume flag does nothing**
 Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change reaches music already playing within a second on macOS hooks (it eases there), at the next loop boundary elsewhere, and in the wrapper or MCP on their next run; `vibe --status` shows the volume in effect and what set it.
 
@@ -837,8 +877,8 @@ Step 3 reclaims disk — the audio cache, pruned to the 3 most recent projects
 
 | Leftover | Why, and how to remove it |
 | :--- | :--- |
-| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI, Qwen Code and Windsurf. A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
-| `vibeaudio` entries in other apps' MCP configs | VibeAudio never edits those files, so it can't clean them either. Drop the entry from [whichever config you added it to](#-everything-else-claude-desktop-antigravity-via-mcp). |
+| `*.vibeaudio.bak` next to each shared hook config | Your config as it was before the first install — one each for Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Windsurf and Antigravity (if you had a `hooks.json` there). A safety net we won't delete for you; `rm` them once you're happy the real files are correct, and `vibe --uninstall-hooks` prints the path of every one it finds. (Grok and Copilot CLI leave nothing: their files are ours alone, so uninstall deletes them outright.) |
+| `vibeaudio` entries in other apps' MCP configs | VibeAudio never edits those files, so it can't clean them either. Drop the entry from [whichever config you added it to](#-everything-else-claude-desktop-vs-code-via-mcp). |
 
 Apart from those two, the three commands above remove everything VibeAudio writes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.14.1",
+  "version": "0.15.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",
@@ -10,8 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
-    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json",
-    "postinstall": "node scripts/postinstall.js"
+    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -23,7 +22,6 @@
   "files": [
     "bin/",
     "src/",
-    "scripts/postinstall.js",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -87,7 +87,7 @@ Procedural focus music while your AI coding tools think.
       --clear-cache            Delete cached audio, then exit
       --mcp                    Run as Model Context Protocol (MCP) server for Desktop apps
       --install-hooks          Wire music into your agent's hooks (no wrapper needed)
-      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen,windsurf (auto-detect)
+      --tools <list>           With --install-hooks: claude,codex,cursor,grok,gemini,copilot,qwen,windsurf,antigravity (auto-detect)
       --reactive               With --install-hooks: intensity follows the tool in use
       --dry-run                With --install-hooks: show what would change, write nothing
       --uninstall-hooks        Remove the hooks again, from every agent
@@ -604,7 +604,7 @@ function installHookTargets(ids, genre, volume, reactive, dryRun = false, typed
     }
     console.log(`  ${events.start.padEnd(19)}→ music starts (${genre} @ ${Math.round(volume * 100)}%)`);
     console.log(`  ${events.stop.padEnd(19)}→ music stops + success chime`);
-    if (reactive) {
+    if (result.reactive) { // off for a target with no pre-tool event
       console.log(`  ${events.tool.padEnd(19)}→ intensity follows the tool in use (reactive mode)`);
     }
     if (events.wait) console.log(`  ${events.wait[0].padEnd(19)}→ music pauses + "your turn" chime`);
@@ -648,7 +648,7 @@ function printHookPlan({ file, backup, name, before, after, id }, t) {
   const ours = (text) => {
     const map = new Map();
     if (!text) return map;
-    for (const [event, entries] of hooks.hookEntries(JSON.parse(text).hooks, t)) {
+    for (const [event, entries] of hooks.hookEntries(hooks.hooksOf(JSON.parse(text), t), t)) {
       const mine = entries.filter((e) => hooks.isVibeHook(e, id));
       if (mine.length) map.set(event, JSON.stringify(mine));
     }
@@ -1118,8 +1118,8 @@ function readVibeHooks(file, t = null) {
   try {
     const settings = JSON.parse(fs.readFileSync(file, "utf8"));
     const out = [];
-    for (const [event, entries] of Object.entries(settings.hooks || {})) {
-      for (const entry of entries || []) {
+    for (const [event, entries] of Object.entries(require("./hooks").hooksOf(settings, t) || {})) {
+      for (const entry of Array.isArray(entries) ? entries : []) {
         for (const command of commands(entry)) {
           if (VIBE_HOOK_FLAG.test(command || "")) out.push({ event, command });
         }
@@ -1430,7 +1430,7 @@ function hooksAlreadyCover(cmdArgs, settingsFile = null) {
     if (!fs.existsSync(file)) return false;
 
     const settings = JSON.parse(fs.readFileSync(file, "utf8"));
-    return Object.values(settings.hooks || {}).some((entries) =>
+    return Object.values(hooks.hooksOf(settings, hooks.TARGETS[id]) || {}).some((entries) =>
       // Not `.some(hooks.isVibeHook)` - Array.some would pass the index as the
       // target id and every lookup would throw.
       (entries || []).some((entry) => hooks.isVibeHook(entry, id))

package/src/hooks.js

@@ -106,9 +106,16 @@ function payloadToolName(raw) {
   return String(payload.tool_name || payload.toolName || byEvent);
 }
 
-// Windsurf calls the conversation `trajectory_id`.
+// Windsurf calls the conversation `trajectory_id`; Antigravity, `conversationId`.
 function payloadSession(payload) {
-  return payload.session_id || payload.trajectory_id;
+  return payload.session_id || payload.trajectory_id || payload.conversationId;
+}
+
+/** The project a hook fired in: `cwd` for most agents, Antigravity's first workspace. */
+function payloadProject(payload) {
+  if (typeof payload.cwd === "string" && payload.cwd) return payload.cwd;
+  const ws = Array.isArray(payload.workspacePaths) ? payload.workspacePaths[0] : null;
+  return typeof ws === "string" && ws ? ws : null;
 }
 
 /**
@@ -346,6 +353,36 @@ const TARGETS = {
     seed: () => ({}),
     liveReload: false,
     note: "Windsurf's hooks do not load in Restricted Mode, and whether an open session reloads them is not documented — start a new one to be sure."
+  },
+  antigravity: {
+    name: "Antigravity",
+    cmd: "agy",
+    // Verified live with the agy CLI 1.1.25 (a logging hook in this file, two
+    // turns): ~/.gemini/config/ is Antigravity's global customization root,
+    // and its hooks.json holds *named* hooks - {"<name>": {"<Event>": [...]}} -
+    // so ours live under a key of their own (hooksKey) and nobody else's are
+    // touched. Handlers are flat for these two events; timeout in seconds.
+    // - start: there is no prompt event. PreInvocation fires before every model
+    //   call with invocationNum counting from 0 per turn; newTurn() marks the
+    //   later ones `continues` and hookStart ignores them.
+    // - stop: Stop, with terminationReason (outcomeFromPayload).
+    // - no tool slot, deliberately: PreToolUse must answer with a decision,
+    //   and a hook that printed none was seen to DENY the tool, while "allow"
+    //   would bypass the user's permission prompts. So --reactive cannot apply.
+    // - no wait, failure, resume or end: there is no permission or session-end
+    //   event, and PostToolUse.error stayed empty for a failing command.
+    // Not verified: the desktop app reading this file (2.19.1 was running and
+    // fired nothing, but was idle), and what Esc fires.
+    file: () => path.join(os.homedir(), ".gemini", "config", "hooks.json"),
+    // ~/.gemini is Gemini CLI's too; this directory is Antigravity's alone.
+    configDir: () => path.join(os.homedir(), ".gemini", "antigravity"),
+    hooksKey: "vibeaudio",
+    events: { start: "PreInvocation", stop: "Stop" },
+    entry: (command) => ({ type: "command", command, timeout: 5 }),
+    commands: (entry) => (entry.hooks ? entry.hooks.map((h) => h.command) : entry.command ? [entry.command] : []),
+    seed: () => ({}),
+    liveReload: false,
+    note: "Not checked whether an open Antigravity session reloads hooks — start a new one to be sure. Reactive mode does not apply: Antigravity's pre-tool hook must approve or deny every tool, so VibeAudio installs none."
   }
 };
 
@@ -580,7 +617,17 @@ 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) || ""), project: payload.cwd || process.cwd(), transcript, offset, blocked: blockedJustBefore(transcript, offset) };
+  return {
+    session: String(payloadSession(payload) || ""),
+    project: payloadProject(payload) || process.cwd(),
+    transcript,
+    offset,
+    blocked: blockedJustBefore(transcript, offset),
+    // Antigravity has no prompt event: its start is PreInvocation, which fires
+    // before every model call and counts them from 0 within the turn. Only the
+    // first one is a new turn; the rest would restart the music mid-turn.
+    continues: Number(payload.invocationNum) > 0
+  };
 }
 
 const BLOCK_LOOKBACK_MS = 3000;
@@ -928,6 +975,7 @@ function spawnDaemon(genre, volume, reactive, follow = false) {
  */
 function hookStart(genre, volume, { reactive = false, turn = null, follow = false } = {}) {
   if (turn && turn.blocked) return null; // Rejected before it began: nothing to play for.
+  if (turn && turn.continues) return null; // A later model call in a turn already playing.
   const id = sessionId(turn && turn.session);
   // Before the spawn: the daemon reads it on startup.
   const project = (turn && turn.project) || process.cwd();
@@ -952,7 +1000,10 @@ function outcomeFromPayload(raw) {
   const payload = parsePayload(raw);
   if (payload.hook_event_name === "StopFailure") return "failure";
   const status = String(payload.status || "").toLowerCase();
-  return status === "error" || status === "aborted" ? "failure" : "success";
+  if (status === "error" || status === "aborted") return "failure";
+  // Antigravity's Stop: NO_TOOL_CALL is the normal end (seen live; its docs
+  // say model_stop). An error or the step limit is a turn that did not finish.
+  return /error|max_steps/i.test(String(payload.terminationReason || "")) ? "failure" : "success";
 }
 
 /**
@@ -998,9 +1049,9 @@ function notifyEnabled(env = process.env, config = loadConfig()) {
   return ["1", "true", "on", "yes"].includes(raw);
 }
 
-/** The project a hook fired in: the payload's cwd (Claude, Codex, Gemini), else ours. */
+/** The project a hook fired in: the payload's (see payloadProject), else ours. */
 function sessionLabel(payload, cwd = process.cwd()) {
-  const dir = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : cwd;
+  const dir = payloadProject(payload) || cwd;
   return path.basename(dir.replace(/[\\/]+$/, "")) || "a session";
 }
 
@@ -1044,14 +1095,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 (tracked) emitEvent("finished", id, payloadProject(parsePayload(raw)) || 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);
     // 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 });
+    recordTurn({ project: payloadProject(parsePayload(raw)) || 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.
@@ -1244,6 +1295,19 @@ function setHook(hooks, event, command, id) {
   hooks[event] = kept;
 }
 
+/**
+ * The object holding a target's events inside its config file: `hooks` for
+ * every agent but Antigravity, whose file is a map of named hooks and keeps
+ * ours under a name of their own (`hooksKey`).
+ */
+function hooksKey(t) {
+  return (t && t.hooksKey) || "hooks";
+}
+
+function hooksOf(settings, t) {
+  return settings ? settings[hooksKey(t)] : undefined;
+}
+
 /** [event, entries] for every event in a hooks object, skipping settings keys. */
 function hookEntries(hooks, t) {
   const configKeys = (t && t.configKeys) || [];
@@ -1253,7 +1317,7 @@ function hookEntries(hooks, t) {
 function readVibeEntryCount(file, id) {
   try {
     const { settings } = loadSettings(file, target(id));
-    return hookEntries(settings.hooks, target(id)).reduce(
+    return hookEntries(hooksOf(settings, target(id)), target(id)).reduce(
       (n, [, entries]) => n + entries.filter((e) => isVibeHook(e, id)).length,
       0
     );
@@ -1285,14 +1349,15 @@ function loadSettings(file, t = null) {
   if (settings === null || typeof settings !== "object" || Array.isArray(settings)) {
     throw new Error(`${file} does not contain a JSON object — refusing to overwrite it.`);
   }
-  if (settings.hooks !== undefined) {
-    if (settings.hooks === null || typeof settings.hooks !== "object" || Array.isArray(settings.hooks)) {
-      throw new Error(`${file} has a "hooks" key that is not an object — refusing to overwrite it.`);
+  const key = hooksKey(t);
+  if (settings[key] !== undefined) {
+    if (settings[key] === null || typeof settings[key] !== "object" || Array.isArray(settings[key])) {
+      throw new Error(`${file} has a "${key}" key that is not an object — refusing to overwrite it.`);
     }
-    for (const [event, entries] of hookEntries(settings.hooks, t)) {
+    for (const [event, entries] of hookEntries(settings[key], t)) {
       if (!Array.isArray(entries)) {
         throw new Error(
-          `${file} has hooks.${event} as ${Array.isArray(entries) ? "an array" : typeof entries}, ` +
+          `${file} has ${key}.${event} as ${Array.isArray(entries) ? "an array" : typeof entries}, ` +
           `not an array of entries — refusing to overwrite it.`
         );
       }
@@ -1354,33 +1419,39 @@ function installHooks(genre = "lofi", volume = 0.4, file = null, { reactive = fa
   }
 
   const ev = t.events;
-  settings.hooks = settings.hooks || {};
-  setHook(settings.hooks, ev.start, hookCommand("--hook-start", genre, volume, reactive), id);
-  setHook(settings.hooks, ev.stop, hookCommand("--hook-stop", genre, volume), id);
+  // Reactive needs a pre-tool event we can listen on without deciding for the
+  // agent; where there is none (Antigravity) it is off, not carried as a flag
+  // that does nothing and that --status would then report.
+  reactive = reactive && Boolean(ev.tool);
+  const key = hooksKey(t);
+  settings[key] = settings[key] || {};
+  const hooks = settings[key];
+  setHook(hooks, ev.start, hookCommand("--hook-start", genre, volume, reactive), id);
+  setHook(hooks, ev.stop, hookCommand("--hook-stop", genre, volume), id);
 
   // Only reactive mode needs per-tool-call signalling.
   if (reactive) {
-    setHook(settings.hooks, ev.tool, hookCommand("--hook-tool", genre, volume), id);
-  } else if (settings.hooks[ev.tool]) {
-    const kept = settings.hooks[ev.tool].filter((entry) => !isVibeHook(entry, id));
-    if (kept.length) settings.hooks[ev.tool] = kept;
-    else delete settings.hooks[ev.tool];
+    setHook(hooks, ev.tool, hookCommand("--hook-tool", genre, volume), id);
+  } else if (ev.tool && hooks[ev.tool]) {
+    const kept = hooks[ev.tool].filter((entry) => !isVibeHook(entry, id));
+    if (kept.length) hooks[ev.tool] = kept;
+    else delete hooks[ev.tool];
   }
 
   for (const event of ev.wait || []) {
-    setHook(settings.hooks, event, hookCommand("--hook-wait", genre, volume), id);
+    setHook(hooks, event, hookCommand("--hook-wait", genre, volume), id);
   }
   // The agent awaits a resume before the next tool's permission check, so a
   // resume can never land after the next wait.
   // ponytail: one ~40ms node start per tool call; a shell-side existence
   // check on the waiting file would skip it if that ever shows.
   for (const event of ev.resume || []) {
-    setHook(settings.hooks, event, hookCommand("--hook-resume", genre, volume, reactive), id);
+    setHook(hooks, event, hookCommand("--hook-resume", genre, volume, reactive), id);
   }
-  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);
+  if (ev.failure) setHook(hooks, ev.failure, hookCommand("--hook-stop", genre, volume), id);
+  if (ev.end) setHook(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);
+  if (ev.interrupt) setHook(hooks, ev.interrupt, hookCommand("--hook-end", genre, volume), id);
 
   const after = `${JSON.stringify(settings, null, 2)}\n`;
   if (!dryRun) fs.writeFileSync(file, after);
@@ -1457,18 +1528,20 @@ function uninstallHooks(file = null, { id = "claude" } = {}) {
   }
 
   const { settings } = loadSettings(file, t);
-  if (!settings.hooks) return { file, removed: 0, id };
+  const key = hooksKey(t);
+  const hooks = settings[key];
+  if (!hooks) return { file, removed: 0, id };
 
   let removed = 0;
-  for (const [event, entries] of hookEntries(settings.hooks, t)) {
+  for (const [event, entries] of hookEntries(hooks, t)) {
     const kept = entries.filter((entry) => !isVibeHook(entry, id));
     removed += entries.length - kept.length;
 
-    if (kept.length) settings.hooks[event] = kept;
-    else delete settings.hooks[event];
+    if (kept.length) hooks[event] = kept;
+    else delete hooks[event];
   }
 
-  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  if (Object.keys(hooks).length === 0) delete settings[key];
   fs.writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
   return { file, removed, id };
 }
@@ -1513,6 +1586,7 @@ module.exports = {
   isVibeHook,
   userHooksInstalled,
   hookEntries,
+  hooksOf,
   installSlashCommand,
   uninstallSlashCommand,
   VIBE_HOOK_FLAG,

package/src/interactive.js

@@ -36,6 +36,7 @@ const AI_TOOLS = [
   { name: "GitHub Copilot CLI", cmd: ["copilot"], check: "copilot", hookTarget: "copilot" },
   { name: "Qwen Code", cmd: ["qwen"], check: "qwen", hookTarget: "qwen" },
   { name: "Windsurf", cmd: ["windsurf"], check: "windsurf", hookTarget: "windsurf" },
+  { name: "Antigravity CLI", cmd: ["agy"], check: "agy", hookTarget: "antigravity" },
   { name: "Aider", cmd: ["aider"], check: "aider" },
   { name: "Ollama (Llama 3)", cmd: ["ollama", "run", "llama3"], check: "ollama" },
   { name: "Custom command...", cmd: null }

package/src/mcp.js

@@ -1,7 +1,7 @@
 /**
  * Model Context Protocol (MCP) Stdio Server
- * Connects VibeAudio to clients with no hook system (Claude Desktop, Antigravity,
- * Gemini CLI). Claude Code, Codex and Cursor have hooks — use those instead.
+ * Connects VibeAudio to clients with no hook system (Claude Desktop, VS Code,
+ * older Gemini CLI releases). Agents with hooks (see TARGETS in hooks.js) should use those.
  * Zero dependencies - Pure Node.js JSON-RPC 2.0 over Stdio
  */
 

package/scripts/postinstall.js

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