---

Table of Contents

• Why Notification Bell?
• Requirements
• Installation
• Quick Start
• Claude Code Integration
• Terminal Watching (Other Agents)
• How It Works
• Features
• 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
• 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"]

That's it. The bell fires the moment your agent needs you.

---

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

---

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

Claude Code Hook

Debug

---

Bundled sounds

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

No configuration needed — open the command and click to switch.

---

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

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

---

Common configuration examples

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

---

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