Never miss an AI agent waiting on you again.
Plays a sound and sends an OS notification the moment your AI agent needs attention — whether it's waiting for confirmation, asking to run a command, or finished its turn.
Works with Claude Code, aider, Gemini CLI, Codex CLI, Cursor CLI, and any other terminal-based AI agent.
Why Notification Bell?RequirementsInstallationQuick StartClaude Code IntegrationTerminal Watching (Other Agents)How It WorksFeaturesCommandsSettingsTuning Patterns for Your AgentLimitationsSupport the ProjectContributing
When AI agents run long tasks you switch to another window — and miss the moment they stop to ask you something. Every missed prompt means waiting for the agent to time out or lose context.
Notification Bell closes that gap:
Instant audio alert the moment an agent needs your inputOS notification so you're notified even when VS Code isn't focusedStatus bar badge🔔 7
showing how many alerts fired this sessionReminder escalation— re-alerts every N minutes if you still haven't responded** Zero configuration**required — sensible defaults work out of the box
VS Code 1.93.0 or latermacOS— usesafplay
(built-in, no install needed)Linux— usespaplay
(PulseAudio) oraplay
(ALSA);notify-send
for OS notifications (libnotify-bin
on Debian/Ubuntu)Windows— uses PowerShellSoundPlayer
; no additional dependenciesClaude Code integration— requires Claude Code installed (~/.claude/
must exist)
Search "Notification Bell" in the VS Code Extensions view (Ctrl+Shift+X
), or run:
code --install-extension chahe-dridi.agent-confirm-sound
1. Install the extension — the status bar shows 🔔
when active.
2. For Claude Code users — accept the setup prompt on first launch, or run:
Ctrl+Shift+P
→Notification Bell: Set Up Claude Code Integration
3. For other agents — it works automatically. Use terminalNameFilter
to limit which terminals are watched:
"agentConfirmSound.terminalNameFilter": ["claude"]
That's it. The bell fires the moment your agent needs you.
On first install, Notification Bell offers to set up a direct integration with Claude Code. Accept and it will:
- Copy the notification sound to
~/.claude/agent-bell-notify.wav
— a stable path that survives extension updates - Add hooks to
~/.claude/settings.json
:
| Hook | Fires when |
|---|---|
Stop |
|
| Claude finishes its turn and is waiting for your next message | |
Notification |
|
| Claude Code sends a background notification (e.g. window not focused) |
These hooks run directly from Claude Code's process — they work even when VS Code is not in focus. Each hook also writes to ~/.claude/agent-bell-signal
so the extension can flash the status bar and show an OS notification inside VS Code.
To set up manually:
Ctrl+Shift+P
→ Notification Bell: Set Up Claude Code Integration
To remove:
Ctrl+Shift+P
→ Notification Bell: Remove Claude Code Integration
PreToolUse hook:If you run Claude Code with manual bash approval (requiresApproval
), enableagentConfirmSound.hookPreToolUse: true
and reinstall the integration. Leave this off if bash is auto-approved — it would fire on every command.
Before uninstalling:runNotification Bell: Remove Claude Code Integration
first to clean up hooks and the copied sound file from~/.claude/
.
Privacy:Notification Bell only writes to your local~/.claude/settings.json
. No data is read, collected, or sent anywhere.
For agents running in a standard VS Code terminal — aider, Gemini CLI, custom scripts — Notification Bell watches terminal output and plays a sound when a line matches a configured regex pattern such as (y/n)
, Allow this action?
, or Press enter to confirm
.
Requires shell integration, which is on by default for bash, zsh, fish, and PowerShell in recent VS Code. A small decoration appears to the left of your prompt when it's active.
Quick setup for common agents:
| Agent | terminalNameFilter value |
|---|---|
| Claude Code | ["claude"] |
| aider | ["aider"] |
| Gemini CLI | ["gemini"] |
| Codex CLI | ["codex"] |
Leave the filter empty ([]
) to watch all terminals.
Claude Code (UI / CLI)
└── ~/.claude/settings.json hooks
├── Stop → plays sound + writes ~/.claude/agent-bell-signal
└── Notification → plays sound + writes ~/.claude/agent-bell-signal
└── fs.watch() in extension
└── status bar flash + OS notification
Other terminal agents (aider, Gemini CLI, scripts, etc.)
└── VS Code shell integration API
└── pattern match on terminal output
└── sound + status bar flash + OS notification
| Feature | |
|---|---|
| 🪝 | Claude Code hook integration — works without shell integration, even when VS Code is not focused |
| 🔊 | Sound alert on any configurable regex pattern in terminal output |
| ⏱️ | Command-end alert — plays when long-running commands finish (configurable minimum duration) |
| 🔔 | Status bar badge — shows session alert count (🔔 7 ), flashes on alert, click to /resume |
| 🖥️ | OS notification when VS Code is not focused (Windows balloon / macOS notification center / Linux notify-send) |
| ⏰ | Reminder escalation — re-alerts after N minutes if you haven't responded |
| 🎵 | Two bundled sounds + support for custom files with random or fixed rotation |
| 🔉 | Volume control on all platforms (afplay / paplay / WAV sample scaling on Windows) |
| 🔍 | Terminal name filter — watch only terminals named "claude" or "aider" |
| 🧪 | Pattern tester — paste terminal output, see which pattern matched, copies regex to clipboard |
| 📋 | Alert history — last 50 alerts with time, source, and trigger |
| 🛠️ | Reset to Defaults command |
| 🌍 | Cross-platform — macOS, Windows, Linux |
Open the Command Palette (Ctrl+Shift+P
) and type "Notification Bell":
| Command | Description |
|---|---|
Notification Bell: Toggle Watching |
|
| or resume terminal watching. Also available via status bar click. | |
Notification Bell: Play Test Sound |
|
| Play the alert sound immediately to verify audio is working. | |
Notification Bell: Show Log |
|
| Open the output channel for match logs and debug info. | |
Notification Bell: Test Pattern |
|
| Enter terminal output — see which pattern matched and copies the regex to clipboard. | |
Notification Bell: Set Up Claude Code Integration |
|
Install Stop + Notification hooks into ~/.claude/settings.json . |
|
Notification Bell: Remove Claude Code Integration |
|
| Remove hooks and delete the copied sound file. Run before uninstalling. | |
Notification Bell: Manage Sounds |
|
| Switch between bundled sounds, add custom files, toggle random mode. | |
Notification Bell: Add Sound File |
|
| Browse and add a custom sound file (.wav / .mp3 / .aiff). | |
Notification Bell: Show Alert History |
|
| View the last 50 alerts this session — time, source, and what triggered each. | |
Notification Bell: Reset to Defaults |
|
| Reset all Notification Bell settings to their defaults. |
Open Settings (Ctrl+,
) and search "Notification Bell", or add to settings.json
:
| Setting | Default | Description |
|---|---|---|
agentConfirmSound.enabled |
||
true |
||
| Turn terminal watching on/off. | ||
agentConfirmSound.patterns |
||
| (see below) | ||
| Case-insensitive regex array matched against terminal output. | ||
agentConfirmSound.terminalNameFilter |
||
[] |
||
| Only watch terminals whose name contains one of these strings. Empty = watch all. | ||
agentConfirmSound.debounceMs |
||
4000 |
||
| Minimum ms between alerts per terminal — prevents repeated sounds on the same prompt. |
| Setting | Default | Description |
|---|---|---|
agentConfirmSound.sounds |
||
[] |
||
| List of custom sound file paths. Empty = use bundled sound. | ||
agentConfirmSound.soundMode |
||
"fixed" |
||
"fixed" uses the first sound. "random" picks one at random each alert. |
||
agentConfirmSound.volume |
||
1 |
||
| Volume 0–1. Applied via afplay (macOS), paplay (Linux), WAV sample scaling (Windows). |
| Setting | Default | Description |
|---|---|---|
agentConfirmSound.focusTerminal |
||
false |
||
| Auto-focus the matching terminal when an alert fires. | ||
agentConfirmSound.alertOnCommandEnd |
||
true |
||
| Play a sound when any long-running terminal command finishes. | ||
agentConfirmSound.commandEndMinDurationMs |
||
3000 |
||
Minimum command duration (ms) before "command finished" fires. Quick commands like ls are ignored. |
||
agentConfirmSound.osNotification |
||
true |
||
| Show an OS-level notification when VS Code is not focused. | ||
agentConfirmSound.reminderIntervalMs |
||
0 |
||
Re-alert after this many ms if you haven't responded. 0 = disabled. |
||
agentConfirmSound.reminderMaxCount |
||
3 |
||
| Maximum number of reminders before stopping. |
| Setting | Default | Description |
|---|---|---|
agentConfirmSound.hookPreToolUse |
||
false |
||
| Also fire on Claude Code's PreToolUse(Bash) hook. Only useful with manual bash approval. |
| Setting | Default | Description |
|---|---|---|
agentConfirmSound.debugLog |
||
false |
||
| Log every terminal chunk to the output channel. Use to tune patterns — disable when done. |
Two sounds ship with the extension, selectable from Notification Bell: Manage Sounds:
| Sound | Description |
|---|---|
notify.wav |
|
| Short, crisp chime (default) | |
notification-bell.mp3 |
|
| Fuller bell tone |
No configuration needed — open the command and click to switch.
"agentConfirmSound.patterns": [
"\\(y\\s*/\\s*n\\)",
"\\[y\\s*/\\s*n\\]",
"\\(Y\\s*/\\s*n\\)",
"\\[Y\\s*/\\s*n\\]",
"do you want to proceed",
"do you want to continue",
"allow this (action|command|tool)",
"would you like to proceed",
"press enter to confirm",
"confirm\\?\\s*$",
"proceed\\?\\s*$",
"continue\\?\\s*$",
"\\(yes/no\\)",
"type ['\"]?yes['\"]? to continue",
"allow (read|write|execute|bash|edit|create|delete|tool)",
"do you want claude",
"waiting for (your )?input",
"execute.*\\?",
"overwrite.*\\?",
"enter (your )?choice",
"are you sure\\?",
"\\[A\\]llow",
"press any key"
]
Patterns removed for causing false positives:
"approve|reject.*action"
(bare word too broad),"tool (call|use|request)"
(matched Claude's own log lines),"run this command"
(matched narration).
Watch only Claude Code terminals:
"agentConfirmSound.terminalNameFilter": ["claude"]
Custom sound at half volume:
"agentConfirmSound.sounds": ["/Users/you/sounds/ping.wav"],
"agentConfirmSound.volume": 0.5
Multiple sounds in random rotation:
"agentConfirmSound.sounds": [
"/Users/you/sounds/ping.wav",
"/Users/you/sounds/chime.wav"
],
"agentConfirmSound.soundMode": "random"
2-minute reminders, up to 3 times:
"agentConfirmSound.reminderIntervalMs": 120000,
"agentConfirmSound.reminderMaxCount": 3
Every agent phrases prompts differently. To find the exact text yours outputs:
-
Set
"agentConfirmSound.debugLog": true -
Open Notification Bell: Show Log - Trigger a prompt in your agent
-
Copy the
[debug]
line text - Run
Notification Bell: Test Pattern and paste it — shows which pattern matched and copies the regex to your clipboard - Paste directly into
agentConfirmSound.patterns
insettings.json
- Set
"agentConfirmSound.debugLog": false
when done
- Terminal watching requires shell integration. Full-screen TUI apps that repaint the terminal (like Claude Code CLI in interactive mode) may not expose clean text — use the Claude Code hook integration instead.
PreToolUse
fires beforeevery bash command, not just approval prompts. LeavehookPreToolUse
off unless you use manual approval mode.- Volume scaling only applies to uncompressed 16-bit PCM WAV files. MP3 and other formats play at their encoded volume on Windows.
- Linux OS notifications require
notify-send
(libnotify-bin
on Debian/Ubuntu,libnotify
on Arch). The extension logs a warning if it's missing. - The Claude Code hook integration requires Claude Code to be installed (
~/.claude/
must exist).
If Notification Bell saves you from missing a prompt, a ⭐ on GitHub helps others find it.
Found a bug or want to add support for a new agent? Contributions are welcome.
See ** CONTRIBUTING.md** for the full guide — branch strategy, pattern rules, and dev environment setup.
Look for good first issue labels to find something to work on.
Branch strategy: all PRs go against dev
, not master
. master
is the stable marketplace branch.
git clone https://github.com/chahe-dridi/vscode-agent-bell.git
cd vscode-agent-bell
git checkout dev
npm install
npm run compile
npm run package
code --install-extension dist/agent-confirm-sound-<version>.vsix --force