AI Agent Sound Notification

A VS Code extension that plays a distinct sound when Claude Code requires your authorization — so you never miss a prompt, even when multitasking.

Not compatible with Google Antigravity — see Why no Antigravity? below.

Features

• 🔔 Distinct alert sound when agents need your approval (commands, file edits, etc.)
• ✅ Completion sound when an agent finishes a turn that didn't need approval (so you know it's done)
• 🎵 27 built-in sounds — 16 Material Design (Google, CC-BY 4.0) + 11 in-house synthesized (chime, bell, harp, fanfare, zen bowl, failure tone, and more)
• ⏱️ Initial delay — gives you time to react before the sound plays (configurable, default 10s)
• 🔁 Configurable repeat with back-off — escalating intervals so you don't forget (off by default)
• 🖥️ Per-window scope — activity in one VS Code window only snoozes alerts for that window
• 🌍 Cross-platform — Windows (PowerShell), macOS (afplay), Linux (paplay/aplay/play)
• 🌙 Windows Focus Assist aware — optional DND mode respect (silently no-op on macOS/Linux)
• 📊 Status bar indicator — visual cue when a prompt is pending

Supported Agents

Installation

From a released .vsix

Download the latest .vsix from the Releases page and install it:

• VS Code GUI: Extensions panel → … menu → Install from VSIX… → pick the file.
• CLI: code --install-extension ai-agent-sound-notification-<version>.vsix

From source

git clone https://github.com/mayerwin/AI-Agent-Sound-Notification.git
cd AI-Agent-Sound-Notification
npm install
npm run package        # auto-bumps version + builds .vsix

Then install the resulting ai-agent-sound-notification-<version>.vsix from the Extensions panel.

For the full developer workflow — Extension Development Host, the master test prompt, debugging, and troubleshooting — see DEVELOPMENT.md.

Configuration

All settings are under aiAgentSoundNotification.* in VS Code Settings:

Built-in sounds

Use the AI Agent Sound: Choose Built-In Sound... command for a live-preview picker, or set soundName directly.

There are two sets of built-in sounds:

• Material Design (Google) — names start with md-. Professionally produced UI sounds from Google's Material Design Sound Resources (CC-BY 4.0). These are the defaults and generally sound nicer.
• Synthesized (in-house) — short names. Generated programmatically; kept as alternatives for users who prefer them or want a more distinctive tone.

Material Design (Google)

Synthesized (in-house)

Custom Back-off Presets

The repeat.intervals array lets you define any back-off pattern:

// Aggressive (for critical workflows)
"aiAgentSoundNotification.repeat.intervals": ["30s", "1m", "2m"]

// Exponential-like (recommended)
"aiAgentSoundNotification.repeat.intervals": ["1m", "5m", "10m", "30m", "1h", "3h"]

// Gentle nudge
"aiAgentSoundNotification.repeat.intervals": ["5m", "15m", "1h"]

How It Works

Claude Code

1. On activation, the extension starts a tiny HTTP server on localhost
2. It registers hooks in ~/.claude/settings.json for the events below
3. When Claude needs you, the hook script pings our server
4. The notification manager plays the sound after the configured delay

The three 🔔 events all fire immediately. We deliberately avoid the Notification event's permission_prompt and idle_prompt matchers, which only fire after a period of inactivity — the delay you want is the one you configure via initialDelay, not one baked into the transport.

Why PostToolBatch and not PostToolUse. Measured on Claude Code 2.1.241: PostToolUse fires only when a tool succeeds, and PostToolUseFailure does not fire at all when a permission prompt is denied — but PostToolBatch fires on all three outcomes (success, failure, denial). It also fires once per batch instead of once per tool, and hook commands sit on the agentic loop's critical path: a 6 s hook added ~4.6 s to a turn's wall time, and four parallel per-tool hooks took 2.35× as long as one. One hook, more coverage, less latency.

Every event carries session_id, and the extension scopes alerts to the session that raised them — the hook script pings every open VS Code window (so the status bar shows up wherever you are), and without scoping a tool finishing in one session would silence a prompt still pending in another.

Workspace Scoping

• The extension registers listeners for file edits within the current workspace
• Editing a file in Window A only dismisses alerts in Window A
• Agent prompts pending in Window B continue to alert independently

Commands

Custom Sound

Replace the built-in sound with any .wav file:

"aiAgentSoundNotification.soundFile": "C:/Users/you/sounds/my-alert.wav"

Platform Support

Focus Assist (DND) detection is Windows-only — respectDND is silently ignored on other platforms.

Completion Sound — Semantics

The completion sound (default md-hero-simple-1) plays when an agent's turn ends and no permission alert was shown during that turn. If you got an alert and approved it, you won't hear the completion ding right after — only the alert had to interrupt you.

The failure sound (default failure, a descending minor third) plays instead when a turn ends because of an API error — rate limit, overloaded, authentication. Those turns fire no Stop event at all, so before this they ended in silence. It is deliberately not the completion sound, because nothing completed, and unlike the completion sound it is not suppressed by an earlier alert in the turn: a dead turn needs you regardless. If you would rather be alerted the same way as a permission prompt, set failureSound.name to your alert sound, or turn it off with failureSound.enabled.

The "did an alert fire this turn?" flag resets when the next user prompt is submitted.

Why no Antigravity?

Earlier versions of this extension shipped Antigravity support via the community antigravity-sdk, which reverse-engineers Antigravity's internal SQLite state DB. It was dropped in v1.0.7 because there is no signal an extension can read that reliably means "the agent is waiting for your approval" or "the turn ended cleanly."

What's actually exposed to third-party extensions:

• No public approval/permission API. The Cascade approval UI lives inside an internal webview, not the VS Code command registry, so there's no onDidRequestPermission or equivalent.
• USS reads are unreliable. In some installs the SDK can't read state.vscdb at all — every key returns 0 bytes. Even when it works, the rich per-step status (StepStatus.WaitingForUser) exists in the protobuf but is never surfaced through any consumer-facing channel.
• No turn-boundary signal. getDiagnostics exposes agentStateDebug and rpcDebug, but they're empty unless an internal Google debug toggle is on.
• The only field that actually moves is lastStepIndex. A step-count delta tells you something happened — but not whether it was an approval prompt, an auto-approved tool, or a status tick. Firing the alert on every delta produces too many false positives to be useful.

By contrast, Claude Code ships a clean, documented hook API with a dedicated event for every state this extension cares about — "permission pending", "question pending", "turn ended", "turn failed". Wiring it up was a few dozen lines of JSON.

Dear Google Antigravity team: please consider exposing a public extension API along the lines of Claude Code's hooks — at minimum an event for "approval pending" and "turn ended." That would let third-party productivity tooling (sound notifications, status mirrors, mobile push, etc.) work reliably without reverse-engineering your internal state. Until then, this extension can't responsibly support Antigravity.

Credits

• Material Design built-in sounds (files prefixed md- under resources/sounds/) are from Google's Material Design Sound Resources, licensed under CC-BY 4.0. Files mirrored locally from the Internet Archive snapshot.

License

MIT — applies to the extension code and the in-house synthesized sounds. Material Design sounds retain their original CC-BY 4.0 license (see Credits).