Agent Idle Notifier (for Claude Code)
Unofficial extension. Not affiliated with or endorsed by Anthropic.
"Claude" and "Claude Code" are trademarks of Anthropic, PBC.
Never miss when Claude Code is done - or waiting for you.
Agent Idle Notifier sends native desktop notifications (Windows Action
Center toast with sound, macOS notification, Linux notify-send) when Claude
Code:
- finishes a task
- asks you a question or waits for your input
- requests permission
It works even when Claude Code runs on a Remote-SSH host, in WSL, or in a
dev container - the notification still reaches your local machine.
日本語
Agent Idle Notifier は、Claude Code が作業を完了したときや、
質問・入力・許可待ちになったときに、OSネイティブのデスクトップ通知を
表示する VS Code 拡張機能です。
Claude Code に作業を任せながら別の画面で仕事をしていても、
作業完了や確認依頼を見逃しにくくなります。
Claude Code が Remote-SSH 先のサーバーや WSL、devコンテナで動いていても、
通知は手元のマシンに届きます。Windows / macOS / Linux 対応。
セットアップはコマンドパレットから
Agent Idle Notifier: Setup for this Workspace を実行するだけです。
Why this exists
The Claude Code VS Code panel only shows a small colored dot on the tab when
it needs attention. If you are in another window, you will miss it. This
extension runs locally (extensionKind: ui), so it can fire real OS
notifications on your machine no matter where Claude Code itself is running.
How it works
- A Claude Code hook (
Notification / Stop / PreToolUse for
questions) writes a tiny JSON event file (.claude-notify.json) at the
project root on whatever machine Claude runs on.
- This extension watches that file through the VS Code file API (which
transparently reaches remote workspaces) and fires a native notification
plus an optional status-bar indicator.
No servers, no telemetry, no dependencies. Two small files.
Setup (one click)
- Install the extension locally (if VS Code asks where, choose Install
Locally, not the SSH host).
- Open your project (local or remote) and run from the Command Palette:
Agent Idle Notifier: Setup for this Workspace
This installs .claude/hooks/agent-idle-notifier.sh and merges the hook
entries into the project's .claude/settings.json. It also adds
.claude-notify.json to your .gitignore if you have one.
- Restart your Claude Code session (or open/close
/config) so it loads the
hooks.
- Verify with
Agent Idle Notifier: Send Test Notification.
Settings
| Setting |
Default |
Description |
agentIdleNotifier.enabled |
true |
Master switch |
agentIdleNotifier.notifyOnStop |
true |
Notify when a turn completes |
agentIdleNotifier.notifyOnPrompt |
true |
Notify when waiting for input / permission |
agentIdleNotifier.osNotification |
true |
Native OS notification |
agentIdleNotifier.useStatusBar |
true |
Status-bar indicator inside VS Code |
agentIdleNotifier.pollIntervalMs |
1000 |
Event poll interval |
Troubleshooting
Run Agent Idle Notifier: Diagnose from the Command Palette and check the
"Agent Idle Notifier" output channel. It reports whether the extension can see
and read the event file, and logs every event and toast attempt.
Notes & limitations
- The
Stop hook fires at the end of every agent turn, not only the final
one, so long agentic runs may notify between steps. Disable notifyOnStop
and keep notifyOnPrompt if that is too chatty.
- The hook needs
bash and python3 on the machine where Claude Code runs
(standard on Linux/macOS; on Windows use WSL or Git Bash).
- Requires the project folder to be the one you have open in VS Code (the
hook also writes to the git root to cover subfolder sessions).
Comparison
Unlike notifier extensions that run on the remote host, this one runs locally,
so Windows toasts and sounds actually reach you over Remote-SSH. It is also
tiny (two files, no dependencies) and installs its own hooks with one command.
License
MIT
