# My AI agent kept waiting on me. I built a VS Code extension to fix that

> Source: <https://github.com/chahe-dridi/vscode-agent-bell>
> Published: 2026-09-03 11:04:09+00:00

**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?](#why-notification-bell)[Requirements](#requirements)[Installation](#installation)[Quick Start](#quick-start)[Claude Code Integration](#claude-code-integration)[Terminal Watching (Other Agents)](#terminal-watching-other-agents)[How It Works](#how-it-works)[Features](#features)[Commands](#commands)[Settings](#settings)[Tuning Patterns for Your Agent](#tuning-patterns-for-your-agent)[Limitations](#limitations)[Support the Project](#support-the-project)[Contributing](#contributing)

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 input**OS notification** so you're notified even when VS Code isn't focused**Status bar badge**`🔔 7`

showing how many alerts fired this session**Reminder 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 later**macOS**— uses`afplay`

(built-in, no install needed)**Linux**— uses`paplay`

(PulseAudio) or`aplay`

(ALSA);`notify-send`

for OS notifications (`libnotify-bin`

on Debian/Ubuntu)**Windows**— uses PowerShell`SoundPlayer`

; no additional dependencies**Claude 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`

), enable`agentConfirmSound.hookPreToolUse: true`

and reinstall the integration. Leave this off if bash is auto-approved — it would fire on every command.

Before uninstalling:run`Notification 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 pause/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` |
Pause 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`

in`settings.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 before**every** bash command, not just approval prompts. Leave`hookPreToolUse`

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](https://github.com/chahe-dridi/vscode-agent-bell/issues?q=is%3Aopen+label%3A%22good+first+issue%22) 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
# Press F5 in VS Code to launch the Extension Development Host
# Build and install locally for testing
npm run package
code --install-extension dist/agent-confirm-sound-<version>.vsix --force
```