Notification Bell

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, and any other terminal-based AI agent.

Install · Claude Code Setup · Settings Panel · Settings · Contributing

Table of Contents

• Why Notification Bell?
• Requirements
• Installation
• Quick Start
• Claude Code Integration
• Terminal Watching (Other Agents)
• How It Works
• Features
• Settings Panel
• Commands
• Settings
• Tuning Patterns for Your Agent
• Limitations
• Support the Project
• Contributing

Why Notification Bell?

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
• Focus mode — keeps the sound but silences OS popups when you don't want banner spam
• 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

Requirements

• 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)

Installation

Search "Notification Bell" in the VS Code Extensions view (Ctrl+Shift+X), or run:

code --install-extension chahe-dridi.agent-confirm-sound

Quick Start

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"]

4. Open the Settings Panel — click the ⚙ gear icon in the status bar to adjust volume, toggle focus mode, and preview sounds without leaving your workflow.

Claude Code Integration

On first install, Notification Bell offers to set up a direct integration with Claude Code. Accept and it will:

1. Copy the notification sound to ~/.claude/agent-bell-notify.wav — a stable path that survives extension updates
2. Add hooks to ~/.claude/settings.json:

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.

Terminal Watching (Other Agents)

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:

Leave the filter empty ([]) to watch all terminals.

How It Works

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

Features

Settings Panel

Click the ⚙ gear icon in the status bar (or run Notification Bell: Open Settings Panel) to open the settings panel in the bottom panel area — the same area as Terminal and Output.

The panel gives you quick access to the most common settings without opening settings.json:

Every row in the panel has an ! info badge — hover it to see a plain-language description of what the setting does.

Commands

Open the Command Palette (Ctrl+Shift+P) and type "Notification Bell":

Settings

Open Settings (Ctrl+,) and search "Notification Bell", or add to settings.json:

Core

Sound

Alerts & Notifications

Claude Code Hook

Debug

Bundled sounds

Two sounds ship with the extension, selectable from Notification Bell: Manage Sounds:

Default patterns

"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"
]

Common configuration examples

Watch only Claude Code terminals:

"agentConfirmSound.terminalNameFilter": ["claude"]

Sound on but no popup banners:

"agentConfirmSound.focusMode": true

Silent when you're actively watching VS Code:

"agentConfirmSound.muteWhenFocused": true

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

Tuning Patterns for Your Agent

Every agent phrases prompts differently. To find the exact text yours outputs:

1. Set "agentConfirmSound.debugLog": true
2. Open Notification Bell: Show Log
3. Trigger a prompt in your agent
4. Copy the [debug] line text
5. Run Notification Bell: Test Pattern and paste it — shows which pattern matched and copies the regex to your clipboard
6. Paste directly into agentConfirmSound.patterns in settings.json
7. Set "agentConfirmSound.debugLog": false when done

Limitations

• 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).

Support the Project

If Notification Bell saves you from missing a prompt, a ⭐ on GitHub helps others find it.

⭐ Star on GitHub

Contributing

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
# 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

CI runs automatically on every PR and checks that the code compiles, no dist/ files are committed, no network calls were introduced, the version was bumped, the CHANGELOG was updated, and no commands or settings were removed. Make sure all checks pass before requesting a review.