AI Agent Notifier
Get a desktop notification with sound when your AI coding agent is waiting on you —
a permission prompt, a question, or a finished turn.
Notifies every time by default — or set it to stay quiet while you're already
looking at the window.
You kick off a long task, switch to your browser, and the agent hits a permission prompt
ten seconds later. You find out ten minutes later.
This extension makes sure you don't.
What you get
- A toast that tells you what's being asked —
Approve Bash: git push --force, or the
actual text of the question — so you can decide whether it's worth switching windows.
- Click it to get there. The notification raises the VS Code window for that project
rather than leaving you to hunt for it.
- A sound, played separately from the toast so it still fires if the toast is blocked.
- A flashing taskbar button (Windows) that keeps pulsing until you switch back.
- Silence when you don't need it. Switch When to notify to Only when unfocused
and nothing fires while the VS Code window for that project already has focus. The
first few notifications remind you the option is there.
Supported agents
| Agent |
Config it writes to |
| Claude Code |
~/.claude/settings.json |
| Codex |
~/.codex/hooks.json |
Both notify when the agent needs approval or asks a question, and when it finishes its
turn.
Codex pauses for a moment while the notification is raised — its hook system has no
non-blocking mode yet. Claude Code doesn't pause.
Getting started
Requires VS Code 1.85 or newer.
Install from the Marketplace, or from a .vsix file:
code --install-extension ai-agent-notifier-0.5.0.vsix
Then:
- The extension detects the agents you have and offers to connect them. Say yes.
- Run AI Notifier: Send Test Notification to confirm you get a toast and a sound.
If you skipped the prompt, run AI Notifier: Open Settings and press Connect next to
your agent.
Commands
All from the Command Palette (Ctrl+Shift+P):
| Command |
What it does |
| AI Notifier: Open Settings |
The settings panel — agents, behaviour, sound, activity log |
| AI Notifier: Send Test Notification |
Fires a notification right now, ignoring all the quiet rules |
| AI Notifier: Install Hooks |
Connects every detected agent |
| AI Notifier: Remove Hooks |
Disconnects every agent and cleans up their config files |
| AI Notifier: Show Status |
Full diagnostics as text, for bug reports |
Settings
All in AI Notifier: Open Settings, or the normal VS Code settings UI under
AI Agent Notifier if you prefer.
| Setting |
Default |
What it does |
aiAgentNotifier.enabled |
on |
Master switch. Stays connected, just goes silent |
aiAgentNotifier.notifyWhen |
always |
Or whenUnfocused to stay quiet while you're looking at the window |
aiAgentNotifier.claudeCode.enabled |
on |
Claude Code on/off |
aiAgentNotifier.claudeCode.events.permissionRequest |
on |
Approvals and questions |
aiAgentNotifier.claudeCode.events.stop |
on |
Turn finished |
aiAgentNotifier.codex.enabled |
on |
Codex on/off |
aiAgentNotifier.codex.events.permissionRequest |
on |
Approvals |
aiAgentNotifier.codex.events.stop |
on |
Turn finished |
aiAgentNotifier.sound.enabled |
on |
Play a sound |
aiAgentNotifier.sound.customPath |
empty |
Your own sound file. .wav on Windows, .aiff/.wav on macOS, .wav/.ogg on Linux |
aiAgentNotifier.flashTaskbar |
on |
Flash the taskbar button. Windows only |
aiAgentNotifier.persistentToast |
off |
Keep the toast up until dismissed |
aiAgentNotifier.macos.useTerminalNotifier |
on |
macOS only. Makes notifications clickable, via terminal-notifier. Inert unless it is installed, and needs allowing in System Settings |
aiAgentNotifier.hookScope |
user |
Or workspace to only affect the current folder. Switching moves the hooks rather than leaving a copy behind |
aiAgentNotifier.autoInstallHooks |
on |
Offer to connect detected agents on first run, and repair the connection after an update. Turn off to manage it yourself |
Turn-finished is the noisy one. That event also fires on /clear, resume and compact.
If it gets annoying, switch it off and keep just the approval prompts.
If it isn't working
Open AI Notifier: Open Settings and look at Activity at the bottom. Every time an
agent triggers the extension it writes a line there.
| What you see |
What it means |
NOTIFY, sound plays, no banner (macOS) |
macOS has notifications turned off for terminal-notifier. Allow it in System Settings → Notifications, or turn Clickable notifications off. |
| Nothing at all |
The agent never triggered it. Press Connect on that agent. |
SILENT — window-focused |
Working correctly: you had When to notify on Only when unfocused and were looking at that window. |
NOTIFY but no toast |
It fired and the OS hid it. Check Focus Assist / Do Not Disturb. |
Two more things:
- After the extension updates, reload the VS Code window. Until you do, the old
version is still running.
- Disconnect your agents before uninstalling. Uninstalling doesn't clean up the agent
config files, and notifications stop with no error.
|
Toast |
Sound |
Click to focus |
Taskbar flash |
Keep toast on screen |
| Windows |
yes |
yes |
not yet confirmed |
yes |
yes |
| macOS |
yes |
yes |
opt-in, often blocked |
— |
— |
| Linux |
not run |
not run |
— |
— |
not run |
Notifications and sound are verified end to end on Windows and macOS. Linux has never
been run on a real machine — it uses the standard notify-send and
paplay/canberra-gtk-play and should work, but treat it as unproven.
Clicking a notification on macOS
Clicking a notification to jump to the project needs
terminal-notifier — an AppleScript
notification cannot carry a click action at all. So:
brew install terminal-notifier- Clickable notifications is on by default; it does nothing until the above is installed
- Allow it in System Settings — see below. This step is the one everybody misses
- Run AI Notifier: Send Test Notification to confirm
⚠️ Heard the sound but saw no notification?
macOS starts terminal-notifier with notifications switched off. Until you allow
them it reports success and draws nothing — so the extension looks broken when a
permission is the whole problem. The sound still plays, because it's a separate process.
System Settings → Notifications → terminal-notifier → Allow Notifications.
Choose Alerts if you want notifications to stay on screen until dismissed, or
Banners if you want them to fade.
The settings panel has an Open macOS notification settings button that takes you
straight there, and offers the same thing after a test notification.
The extension cannot detect this state — terminal-notifier exits 0 either way, and
even reports the notification as delivered. If you'd rather not deal with it, turn
Clickable notifications off: notifications go back to AppleScript and always appear,
but are no longer clickable.
Known limitations
- Focus Assist / Do Not Disturb hides the toast. The sound and taskbar flash still fire.
On Windows you can add Windows PowerShell to the notification priority list to exempt it.
- Windows toasts are attributed to "Windows PowerShell" rather than to this extension.
- A burst of approvals is a burst of notifications. When to notify →
Only when unfocused is what keeps that manageable.
- Connecting an agent rewrites its config file as plain JSON, so comments in that file are
lost. Everything else in it is preserved.
- Remote windows don't work. In Remote-SSH, WSL, Dev Containers or Codespaces, the
extension runs on the remote host along with the agent — so the hooks land in the right
place, but the toast is raised on the remote machine and never reaches your desktop. The
settings panel says so when it detects one.
Privacy
Everything runs locally. The extension makes no network requests and uploads nothing. The
activity log lives at ~/.ai-agent-notifier/shim.log on your machine and keeps the last
200 entries.
Licence
Free to use, personal or commercial. Not open source — see LICENSE.txt, included with the
extension.
