vibeaudio 0.14.2 → 0.16.0

package/README.md

@@ -8,7 +8,7 @@
 
 > **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)**
 
@@ -45,7 +45,8 @@ 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.
+* 🔕 **Signals without the music.** `vibe --music off` keeps the done, failed and "needs you" chimes, banners and the state stream, and drops the music. For people who bring their own, or share an office. ([details](#signals-only-vibe---music-off))
+* 🔌 **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>
@@ -241,7 +242,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.
 
@@ -254,12 +255,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:
 
@@ -273,6 +274,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:
 
@@ -283,12 +285,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>
 
 
 | | |
@@ -296,7 +299,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`. |
@@ -323,9 +327,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.
 
@@ -415,6 +419,22 @@ Removing them is one command:
 vibe --uninstall-hooks
 ```
 
+### Signals only: `vibe --music off`
+
+VibeAudio does two jobs: music while an agent works, and signals (the done, failed and "needs you" chimes, banners, the stuck alert, `--events`). If you only want the second:
+
+```bash
+vibe --music off      # signals only
+vibe --music on       # music back, in the genre you had
+vibe --music off --here   # this project only
+```
+
+It's a setting of its own, saved to `config.json` like genre and volume, so your genre is still there when you turn music back on. Like the others, a flag beats `VIBE_MUSIC=off`, which beats `--here`, which beats the global value, and installed hooks pick it up on the next prompt.
+
+With music off, hooks still track every turn: the chimes, `--notify` banners, `--state`, `--events` and `--report` behave exactly as before, and no background player is started. The wrapper (`vibe npm test`) stays silent while it runs and chimes when a run that outlasted the grace window ends, so it becomes "tell me when it's done". MCP's `vibe_play` tells the model that music is off rather than claiming it started. `vibe --status` and `vibe --doctor` show the setting.
+
+Two things differ from music on. The stuck heartbeat is a layer on the music, so with music off it plays once on its own, the same two soft beats, when a session crosses into stuck (you also get the `stuck` event and, with `--notify`, the banner). And turning music off while something is playing doesn't cut it: `vibe --stop` does, or it ends with the current turn.
+
 ### Know where your time goes: `vibe --report`
 
 Hooks log each finished turn — which project, how long, how it ended, and how much of it the agent spent blocked on a dialog of yours — to `~/.vibeaudio/history.jsonl`. `vibe --report` (or `--report 30`) totals it:
@@ -448,7 +468,7 @@ The worst stretch of agent work is twenty minutes of the same thing failing whil
 
 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>
 
@@ -487,7 +507,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
@@ -506,9 +526,20 @@ Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with
 
 #### 📟 Status Bar & Desktop Integrations
 
-**tmux status bar** — show overall agent state (`waiting`, `stuck`, `working`, or `idle`):
+**`vibe --statusline`** prints the same state as one plain line, with no `jq`, and **nothing at all when idle**, so a prompt segment disappears. It shows the most urgent state, with a count when several sessions are in it, and names the project when one is waiting on you:
+
+```
+working
+working ×2
+stuck
+waiting: api
+```
+
+It is plain text on purpose: tmux and Starship do their own styling. It doesn't run `ps` and doesn't change when you're muted.
+
+**tmux status bar:**
 ```bash
-set -g status-right '#(vibe --state | jq -r .status)'
+set -g status-right '#(vibe --statusline)'
 ```
 
 **macOS speech alert** — announce out loud whenever an agent stops to ask for your input:
@@ -519,17 +550,21 @@ vibe --events | jq --unbuffered -r 'select(.event=="waiting") | .project' | whil
 **Starship prompt** — custom indicator in `~/.config/starship.toml`:
 ```toml
 [custom.vibe]
-command = "vibe --state | jq -r 'if .status != \"idle\" then \"🎧 \" + .status else \"\" end'"
+command = "vibe --statusline"
 when = "command -v vibe >/dev/null"
+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.*
 
 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:
 
@@ -555,7 +590,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.
 
@@ -695,6 +730,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--grace <ms>` | Silence window before music starts | `1500` |
 | `--here` | With a saved setting: this directory tree only, not everywhere | off |
 | `--seed <n>` | Force a specific arrangement | derived from the project directory |
+| `--music <on\|off>` | `off` keeps the chimes, banners and events and drops the music. With no command after it, saves it as a setting. `--here` for one project | `on` |
 | `--whisper` | Quick preset: 15% volume (headphones / late night) | — |
 | `--quiet` | Quick preset: 25% volume (focus / open office) | — |
 | `--loud` | Quick preset: 75% volume (hear from across the room) | — |
@@ -706,6 +742,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--doctor` | Check the setup; every problem comes with the command that fixes it. Exits 1 on a failure, so it scripts | — |
 | `--notify` / `--no-notify` | Also show a desktop banner naming the project when a turn finishes, fails or needs you. Saved to `config.json` | off |
 | `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
+| `--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 | — |
 | `--stop` | Stop the background player, then exit | — |
@@ -714,7 +751,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 | — |
@@ -732,6 +769,7 @@ export VIBE_CHIME_VOLUME=70     # Crisp completion chime at 70%
 export VIBE_GRACE_MS=3000       # Wait 3s of thinking before any music
 export VIBE_SEED=7              # Same arrangement everywhere, ignoring the directory
 export VIBE_DISABLE=1           # Mute, without uninstalling anything
+export VIBE_MUSIC=off           # Signals only: chimes and banners, no music, for this shell
 export VIBE_NOTIFY=1            # Desktop banner naming the project, for this shell
 export VIBE_NO_HISTORY=1        # Do not log finished turns (what --report reads)
 export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
@@ -874,8 +912,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.2",
+  "version": "0.16.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

@@ -17,6 +17,7 @@ const {
   normalizeVolume,
   loadConfig,
   saveConfig,
+  musicEnabled,
   projectSettings,
   saveProjectConfig,
   wavDurationMs,
@@ -68,6 +69,7 @@ Procedural focus music while your AI coding tools think.
       --grace <ms>             Silence window before music starts, in ms (default: ${DEFAULT_GRACE_PERIOD_MS})
       --here                   With a saved setting: this directory only, not everywhere
       --seed <n>               Force a specific arrangement (default: derived from the project directory)
+      --music <on|off>         off = signals only: chimes, banners and events, no music (a saved setting)
       --whisper                Preset: 15% volume (late night / headphones)
       --quiet                  Preset: 25% volume (focus / open office)
       --loud                   Preset: 75% volume (hear from across the room)
@@ -79,6 +81,7 @@ 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
+      --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)
       --stop                   Stop the background player, then exit
@@ -87,7 +90,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
@@ -110,6 +113,7 @@ Procedural focus music while your AI coding tools think.
   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_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
@@ -136,6 +140,7 @@ const VALUE_FLAGS = new Set([
   "-v", "--volume",
   "-cv", "--chime-volume",
   "--grace",
+  "--music",
   "--seed",
   "--tools",
   "--event"
@@ -155,6 +160,7 @@ function parseArgs(argv) {
   const here = projectSettings(saved);
   const setting = (key) => (here[key] !== undefined ? here[key] : saved[key]);
 
+  let music = musicEnabled(process.env, saved);
   let genre = (process.env.VIBE_GENRE || setting("genre") || "lofi").toLowerCase();
 
   let volume = normalizeVolume(process.env.VIBE_VOLUME, normalizeVolume(setting("volume"), 0.40));
@@ -178,6 +184,7 @@ function parseArgs(argv) {
   let clearCacheFlag = false;
   let statusFlag = false;
   let stateFlag = false;
+  let statuslineFlag = false;
   let eventsFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
@@ -295,6 +302,24 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--music") {
+      const value = args[i + 1].toLowerCase();
+      if (value !== "on" && value !== "off") {
+        console.error(`\x1b[31m[vibeaudio] --music takes on or off, not '${args[i + 1]}'.\x1b[0m`);
+        process.exit(1);
+      }
+      music = value === "on";
+      typed.music = music;
+      i += 2;
+      continue;
+    }
+
+    if (arg === "--statusline") {
+      statuslineFlag = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--state" || arg === "--events") {
       if (arg === "--state") stateFlag = true;
       else eventsFlag = true;
@@ -492,6 +517,8 @@ function parseArgs(argv) {
     clearCache: clearCacheFlag,
     status: statusFlag,
     state: stateFlag,
+    statusline: statuslineFlag,
+    music,
     events: eventsFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
@@ -604,7 +631,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 +675,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));
     }
@@ -734,6 +761,7 @@ function printStatus() {
       : off("  default");
 
   console.log(`\x1b[1mSound\x1b[0m`);
+  console.log(`  music     ${musicEnabled() ? on("on") : "\x1b[33moff\x1b[0m"}${source("VIBE_MUSIC", "music")}${musicEnabled() ? "" : off("  signals only — vibe --music on")}`);
   console.log(`  genre     ${on(genreNow())}${source("VIBE_GENRE", "genre")}`);
   console.log(`  volume    ${on(`${Math.round(volumeNow() * 100)}%`)}${source("VIBE_VOLUME", "volume")}`);
   console.log(`            ${off("change either with: vibe --genre <name> --volume <n>")}`);
@@ -943,6 +971,7 @@ function doctorChecks() {
   if (mute !== null) add("warn", "Mute", `muted ${muteRemainingText(mute)}`, "vibe --unmute");
   if (playbackDisabled()) add("warn", "VIBE_DISABLE", `set to "${process.env.VIBE_DISABLE}" — automatic playback is off`, "unset VIBE_DISABLE");
   if (mute === null && !playbackDisabled()) add("ok", "Mute", "not muted");
+  if (!musicEnabled()) add("ok", "Music", "off — chimes and banners only, by your setting (vibe --music on)");
 
   const pid = readDaemonPid(hooks.PID_FILE);
   if (pid === null) add("ok", "Background player", "not running");
@@ -1118,8 +1147,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 });
         }
@@ -1178,6 +1207,7 @@ function saveDefaults(typed, hereOnly = false) {
   if (typed.volume !== undefined) patch.volume = Math.round(typed.volume * 100);
   if (typed.chimeVolume !== undefined) patch.chimeVolume = Math.round(typed.chimeVolume * 100);
   if (typed.grace !== undefined) patch.grace = typed.grace;
+  if (typed.music !== undefined) patch.music = typed.music;
 
   const { CONFIG_FILE } = require("./player");
   if (hereOnly) saveProjectConfig(patch);
@@ -1187,7 +1217,8 @@ function saveDefaults(typed, hereOnly = false) {
     genre: (v) => `genre ${v}`,
     volume: (v) => `volume ${v}%`,
     chimeVolume: (v) => `chime volume ${v}%`,
-    grace: (v) => `grace ${v}ms`
+    grace: (v) => `grace ${v}ms`,
+    music: (v) => `music ${v ? "on" : "off"}`
   };
   const changed = Object.keys(patch).map((k) => label[k](patch[k])).join(", ");
   const where = hereOnly ? ` for ${process.cwd()}` : "";
@@ -1201,6 +1232,12 @@ function saveDefaults(typed, hereOnly = false) {
   if (playing && patch.genre && playing.genre && playing.genre !== patch.genre) {
     console.log(`  \x1b[90m${playing.genre} is still playing — vibe --stop cuts it short.\x1b[0m`);
   }
+  if (playing && patch.music === false) {
+    console.log(`  \x1b[90m${playing.genre || "The music"} is still playing — vibe --stop cuts it short.\x1b[0m`);
+  }
+  if (patch.music === false) {
+    console.log(`  \x1b[90mSignals only: chimes, banners, --events and --report work as before.\x1b[0m`);
+  }
   if (playing && playing.follows && patch.volume !== undefined) {
     console.log(`  \x1b[90mThe music playing now follows the new volume within a second.\x1b[0m`);
   }
@@ -1335,7 +1372,7 @@ function renderToFile(target, genre) {
   console.log(`  \x1b[90mAnother project's sound: run it there, or vibe --seed <n> --render.\x1b[0m\n`);
 }
 
-function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
+function runHookAction(action, { music = true, genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
   if (plugin && action.startsWith("hook-")) {
@@ -1361,7 +1398,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       // The payload names the session (so SessionEnd can tell this session's
       // music from another's) and the transcript (so an interrupt, which
       // fires no hook, can still stop it).
-      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
+      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { music, reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
       return;
 
     case "hook-stop":
@@ -1388,7 +1425,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       return;
 
     case "hook-resume":
-      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive, follow: typed.volume === undefined }));
+      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { music, reactive, follow: typed.volume === undefined, chimeVolume, noChime }));
       return;
 
     case "hook-end":
@@ -1430,7 +1467,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))
@@ -1455,10 +1492,10 @@ function windowsCommandNeedsShell(command) {
   return !/[\\/]/.test(command);
 }
 
-function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false) {
+function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false, music = true) {
   const player = new AudioPlayer();
   const hookDriven = hooksAlreadyCover(cmdArgs);
-  const hud = !noHud && !hookDriven ? new TerminalHud(genre) : null;
+  const hud = !noHud && !hookDriven && music ? new TerminalHud(genre) : null;
   const startTime = Date.now();
   let musicStarted = false;
   let finished = false;
@@ -1486,8 +1523,8 @@ function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRA
 
   // Grace window before triggering audio (silences fast commands)
   const graceTimer = hookDriven ? null : setTimeout(() => {
-    musicStarted = true;
-    player.start(genre, volume);
+    musicStarted = true; // Set with music off too: the chime marks the end of a run that outlasted the grace window.
+    if (music) player.start(genre, volume);
     if (hud) hud.start();
   }, grace);
 
@@ -1566,6 +1603,8 @@ async function run() {
     clearCache: shouldClear,
     status: showStatus,
     state: showState,
+    statusline: showStatusline,
+    music,
     events: followEvents,
     doctor: showDoctor,
     notify: notifyChange,
@@ -1596,7 +1635,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent, tools, dryRun, typed });
+      return runHookAction(hookAction, { music, genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent, tools, dryRun, typed });
     } catch (e) {
       // Settings problems are the user's to fix — report them, don't stack-trace.
       console.error(`\x1b[31m[vibeaudio] ${e.message}\x1b[0m`);
@@ -1667,6 +1706,14 @@ async function run() {
     return;
   }
 
+  // Idle prints nothing, not even a newline, so a prompt segment disappears.
+  if (showStatusline) {
+    const hooks = require("./hooks");
+    const line = hooks.formatStatusline(hooks.agentState());
+    if (line) console.log(line);
+    return;
+  }
+
   if (followEvents) {
     process.stdout.on("error", () => process.exit(0)); // `vibe --events | head` closing the pipe is not an error.
     require("./hooks").followEvents();
@@ -1736,10 +1783,10 @@ async function run() {
       }
     }
 
-    return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud);
+    return executeCommand(selection.cmd, selection.genre, chosenVol, chimeVolume, grace, noChime, noHud, music);
   }
 
-  executeCommand(cmdArgs, genre, volume, chimeVolume, grace, noChime, noHud);
+  executeCommand(cmdArgs, genre, volume, chimeVolume, grace, noChime, noHud, music);
 }
 
 module.exports = {

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;
@@ -708,6 +755,20 @@ function agentState(sessions = listSessions()) {
   return { v: 1, status, sessions: list };
 }
 
+/**
+ * `vibe --statusline`: the state as one plain line for a tmux segment or a
+ * shell prompt, and nothing at all when idle so the segment disappears. The
+ * most urgent status, with a count when more than one session is in it; a
+ * waiting session names its project, since that is the one you have to go to.
+ * Plain text because tmux and Starship style it themselves.
+ */
+function formatStatusline({ status, sessions }) {
+  if (status === "idle") return "";
+  const active = sessions.filter((s) => s.state === status);
+  const project = status === "waiting" && active[0].project ? `: ${projectName(active[0].project)}` : "";
+  return `${status}${project}${active.length > 1 ? ` ×${active.length}` : ""}`;
+}
+
 const EVENTS_MAX_BYTES = 256 * 1024;
 
 /**
@@ -926,8 +987,9 @@ function spawnDaemon(genre, volume, reactive, follow = false) {
  * always did, so a genre change lands on the next prompt. With one working the
  * music carries on: restarting it would cut every other session's stream.
  */
-function hookStart(genre, volume, { reactive = false, turn = null, follow = false } = {}) {
+function hookStart(genre, volume, { reactive = false, turn = null, follow = false, music = true } = {}) {
   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();
@@ -937,6 +999,10 @@ function hookStart(genre, volume, { reactive = false, turn = null, follow = fals
 
   stopDaemon({ keepSessions: true });
   fs.rmSync(INTENSITY_FILE, { force: true }); // Don't inherit the last prompt's activity
+  // Signals only: the session is tracked (chimes, events and the report read
+  // it) but there is no music to start. Stopping first means a switch to off
+  // lands on the next prompt rather than playing until the turn ends.
+  if (!music) return null;
   return spawnDaemon(genre, volume, reactive, follow);
 }
 
@@ -952,7 +1018,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,10 +1067,13 @@ 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 projectName(dir) {
+  return path.basename(String(dir).replace(/[\\/]+$/, "")) || "a session";
+}
+
 function sessionLabel(payload, cwd = process.cwd()) {
-  const dir = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : cwd;
-  return path.basename(dir.replace(/[\\/]+$/, "")) || "a session";
+  return projectName(payloadProject(payload) || cwd);
 }
 
 /**
@@ -1044,14 +1116,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.
@@ -1132,7 +1204,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * one needing approval, can resume early - after the chime already did its
  * job. Match on tool_input as well if that ever shows up in practice.
  */
-function hookResume(raw, genre, volume, { reactive = false, follow = false } = {}) {
+function hookResume(raw, genre, volume, { reactive = false, follow = false, music = true, chimeVolume = null, noChime = false } = {}) {
   const payload = parsePayload(raw);
   const id = sessionId(payloadSession(payload));
   const session = readSession(id);
@@ -1146,7 +1218,13 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false } = {
   const recent = [...(session.recent || []), failed ? 1 : 0].slice(-STUCK_WINDOW);
   const next = { ...session, recent };
   const crossing = isStuck(next) === isStuck(session) ? null : isStuck(next) ? "stuck" : "recovered";
-  if (crossing === "stuck") notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+  if (crossing === "stuck") {
+    notify(raw, `looks stuck - ${STUCK_FAILURES} of its last ${STUCK_WINDOW} tool calls failed`);
+    // With music on the daemon adds the heartbeat; with it off there is no
+    // loop to put one under, so the pulse plays once on its own. Detached: the
+    // agent waits on this hook.
+    if (!music && !noChime) new AudioPlayer().stop({ playChime: true, outcome: "stuck", volume, chimeVolume, detach: true });
+  }
 
   // An empty key is a wait that named nothing (a Notification): the next tool
   // to finish is the first sign of work carrying on.
@@ -1161,7 +1239,7 @@ function hookResume(raw, genre, volume, { reactive = false, follow = false } = {
   writeSession(id, { ...next, waiting: null, waitStart: null, blockedMs });
   emitEvent("resumed", id, session.project);
   if (crossing) emitEvent(crossing, id, session.project);
-  if (!daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
+  if (music && !daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
   return true;
 }
 
@@ -1244,6 +1322,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 +1344,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 +1376,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 +1446,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 +1555,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 };
 }
@@ -1492,6 +1592,7 @@ module.exports = {
   isStuck,
   STUCK_WINDOW,
   agentState,
+  formatStatusline,
   followEvents,
   EVENTS_FILE,
   hookEnd,
@@ -1513,6 +1614,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,12 +1,12 @@
 /**
  * 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
  */
 
 const readline = require("readline");
-const { AudioPlayer, AVAILABLE_GENRES, normalizeVolume, playbackDisabled, isKnownGenre, loadConfig } = require("./player");
+const { AudioPlayer, AVAILABLE_GENRES, normalizeVolume, playbackDisabled, musicEnabled, isKnownGenre, loadConfig } = require("./player");
 const pkg = require("../package.json");
 
 // A desktop client that crashes never sends vibe_stop, so playback needs its
@@ -148,6 +148,15 @@ function handleMessage(player, msg) {
       const volume = normalizeVolume(args.volume,
         normalizeVolume(process.env.VIBE_VOLUME, normalizeVolume(saved.volume, 0.4)));
 
+      // A deliberate setting, like a mute: report it as one, and start nothing.
+      if (!musicEnabled()) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: { content: [{ type: "text", text: "The user has turned VibeAudio's music off (signals only), so nothing will play. This is deliberate and not an error — do not try again or suggest fixes; they will turn it back on when they want music." }] }
+        };
+      }
+
       const started = player.start(genre, volume, { maxDurationMs: MAX_PLAYBACK_MS });
       // start() returns false for three unrelated reasons, and the model
       // relays whatever we say here to the user. Reporting a deliberate mute
@@ -204,6 +213,7 @@ function handleMessage(player, msg) {
                 // Without this, "isPlaying: false" while muted reads as a bug
                 // worth investigating rather than a choice the user made.
                 muted: playbackDisabled(),
+                musicOff: !musicEnabled(),
                 genre: player.genre,
                 currentTier: player.currentTier,
                 uptimeMs: player.isPlaying ? Date.now() - player.startTime : 0

package/src/player.js

@@ -18,7 +18,7 @@ const { generateRainLoop } = require("./synth/rain");
 const { generateOceanLoop } = require("./synth/ocean");
 const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
-const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
+const { generateSuccessChime, generateFailureChime, generateAttentionChime, generateStuckChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
 const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
@@ -430,6 +430,19 @@ function playbackDisabled() {
   return muteState() !== null;
 }
 
+/**
+ * Whether music plays at all, as opposed to `playbackDisabled()`, which
+ * silences everything including the chimes. Some people want only the
+ * signals (done, failed, needs you), so this is a setting of its own rather
+ * than a genre: `genre` stays what it was for when music comes back on.
+ * Env beats this directory's saved value beats the global one; a flag is
+ * resolved by parseArgs() and handed to whoever acts on it.
+ */
+function musicEnabled(env = process.env, config = loadConfig()) {
+  const raw = env.VIBE_MUSIC ?? projectSettings(config).music ?? config.music ?? "on";
+  return !["off", "0", "false", "no"].includes(String(raw).trim().toLowerCase());
+}
+
 /**
  * `minutes` of 0 means indefinite, which the user has to ask for explicitly.
  */
@@ -652,7 +665,8 @@ function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0,
 const CHIMES = {
   success: generateSuccessChime,
   failure: generateFailureChime,
-  attention: generateAttentionChime
+  attention: generateAttentionChime,
+  stuck: generateStuckChime
 };
 
 /**
@@ -965,6 +979,7 @@ module.exports = {
   bakedGain,
   applyGain,
   playbackDisabled,
+  musicEnabled,
   resolveGenre,
   isKnownGenre,
   normalizeVolume,

package/src/synth/chime.js

@@ -143,11 +143,32 @@ function generateAttentionChime(durationSec = 1.3) {
   return createWavBuffer({ left, right, sampleRate: SAMPLE_RATE });
 }
 
+/**
+ * "Looks stuck", for someone with the music off, who has no loop for the
+ * heartbeat to sit under. It is that same heartbeat on its own - two lub-dubs
+ * on A, a resting pulse - so it means what the layer means: not an outcome and
+ * not a question, just something that has not changed for a while. Quiet, and
+ * low enough to read as a pulse rather than a tone.
+ */
+function generateStuckChime(durationSec = 1.8) {
+  const { thump, pulseFreq, BEAT_S, DUB_DELAY_S } = require("./tension");
+  const f = pulseFreq("A minor");
+  const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
+  const out = new Float64Array(totalSamples);
+  for (let i = 0; i < totalSamples; i++) {
+    const t = i / SAMPLE_RATE;
+    const local = t % BEAT_S;
+    out[i] = 0.3 * (thump(local, f) + 0.7 * thump(local - DUB_DELAY_S, f));
+  }
+  return createWavBuffer({ left: out, right: out, sampleRate: SAMPLE_RATE });
+}
+
 module.exports = {
   DEFAULT_CHIME_KEY,
   SUCCESS_CHIME_NOTES,
   generateChime: generateSuccessChime,
   generateSuccessChime,
   generateFailureChime,
-  generateAttentionChime
+  generateAttentionChime,
+  generateStuckChime
 };

package/src/synth/tension.js

@@ -64,4 +64,4 @@ function addTension(wav, key) {
   return out;
 }
 
-module.exports = { addTension, pulseFreq };
+module.exports = { addTension, pulseFreq, thump, BEAT_S, DUB_DELAY_S };