agent-notify

A signal tone and a Windows toast when your coding agent finishes a turn or is waiting for a decision — so you can look away without missing the moment it needs you.

Supports Claude Code, Codex and Antigravity (agy). Windows only.

• Soft, bell-like tones synthesised from scratch, not the harsh Console.Beep square wave. Three timbres to choose from.
• Two distinguishable signals: finished and needs a decision.
• A point-and-click installer that only touches the agents you select, backs up every file it changes, and can be re-run safely.
• No dependencies. No modules to install. Plain PowerShell that ships with Windows.

Install

1. Clone or download this repository.

   git clone https://github.com/RoYaL69/agent-notify.git "$env:USERPROFILE\.agent-notify"

   Any location works — everything resolves relative to the script location.

2. Double-click setup.cmd. The wizard asks two things:

   • Page 1 — which agents to install into. Agents that are not present on the machine are greyed out.
   • Page 2 — which sound set, with a preview button per variant.

3. Restart Codex if you selected it (it reads config.toml only at startup). Claude Code and agy pick the hooks up on the next session.

Without the wizard

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

Options:

.\install.ps1 -Targets Claude,Codex   # Claude | Codex | Antigravity
.\install.ps1 -Variant glass          # chime (default) | glass | marimba
.\install.ps1 -Force                  # re-render the WAV files

Sounds

Variant	Character
chime	Warm major arpeggio C6–E6–G6, soft bell. Unobtrusive. The default.
glass	Brighter and glassier, longer ring-out. More noticeable.
marimba	Woody, short decay, lower register. The most discreet.

The needs a decision signal is the same timbre, struck twice, so the two are easy to tell apart without being jarring.

make-sounds.ps1 renders them with additive synthesis: a sine fundamental plus a few decreasing harmonics, a 4 ms attack to avoid the click, and an exponential decay per partial — higher harmonics fade faster, which is what makes a tone sound struck rather than synthetic. Edit the note tables in that script to write your own.

What gets installed

Agent	File	Entry
Claude Code	~/.claude/settings.json	Stop hook (finished) and Notification hook (decision needed)
Codex	~/.codex/config.toml	notify program
Antigravity	~/.gemini/config/hooks.json	named hook agent-notify, Stop event

Every file is backed up as <file>.<timestamp>.bak before it is modified. Re-running the installer replaces its own entries instead of duplicating them, and leaves everything else in those files untouched.

Codex allows exactly one notify program. If one was already registered — the Codex desktop app registers its computer-use helper there — the installer records it in config.json and codex-notify.ps1 forwards every payload to it, so the existing integration keeps working.

Files

File	Purpose
setup.cmd	Double-click launcher for the wizard
setup.ps1	Two-page wizard: pick agents, pick sound, install
install.ps1	Headless installer, does the actual wiring
notify.ps1	Plays the tone and shows the toast
make-sounds.ps1	Renders done.wav and input.wav
codex-notify.ps1	Codex notify entry point, forwards to the previous program

Requirements

• Windows 10 or 11
• Windows PowerShell 5.1 (powershell.exe, ships with Windows)

The toast uses WinRT APIs that cannot be loaded from PowerShell 7, so notify.ps1 has to run under powershell.exe. The hooks are configured that way; you can still use PowerShell 7 for everything else.

Limitations

• The toast appears under the app name "Windows PowerShell". Using a registered AppUserModelID is what makes it reach the Action Center at all; a custom name would require installing a Start Menu shortcut.
• Claude's Stop hook also fires on /clear, /compact and resume.
• agy has no permission or decision event, and Codex only emits agent-turn-complete. The needs a decision signal is therefore Claude-only.

Silence it

Set the environment variable AGENT_NOTIFY_DISABLE=1.

Test

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\notify.ps1 -Source Test -Kind done
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\notify.ps1 -Source Test -Kind input

License

MIT — see LICENSE.