copilot-notifier

Audio notifications for GitHub Copilot agent activity on macOS.

Plays a sound when the Copilot agent finishes its turn so you can focus on other things and come back when it's done.

Sounds

Event	Sound	When
Agent step	🔵 Pop	The agent completed an LLM call (still running tools)
Agent done	🐸 Frog	The agent finished — your turn to respond
Button waiting	💨 Blow	The agent is likely waiting for you to click Allow/Skip
LLM error	🔴 Basso	An API call failed

Note on Button detection (ORPHAN_DETECTION): There is no reliable log signal that distinguishes "agent waiting for button click" from "agent running a slow tool". The heuristic is: if an LLM response arrived but shouldContinue=false never followed within ORPHAN_TIMEOUT seconds, assume a button is showing. Any tool that runs longer than ORPHAN_TIMEOUT will produce a false Blow. See Configuration below.

Requirements

• macOS
• Python 3 (pre-installed on macOS)

Install

git clone git@github.com:hgromov/copilot-notifications.git
cd copilot-notifications
chmod +x install.sh
./install.sh

The script:

1. Installs a macOS LaunchAgent pointing to this folder
2. Starts the notifier immediately
3. Auto-starts on every login

The log appears in the same folder: notifier.log

Uninstall

./uninstall.sh

Configuration

Edit notifier.py. The configuration block is at the top of the file:

SOUND_DONE     = "/System/Library/Sounds/Frog.aiff"  # agent turn complete
SOUND_STEP     = "/System/Library/Sounds/Pop.aiff"   # agent LLM step
SOUND_ERROR    = "/System/Library/Sounds/Basso.aiff" # LLM API failure
SOUND_QUESTION = "/System/Library/Sounds/Blow.aiff"  # agent waiting for Allow/Skip button

DONE_COOLDOWN = 5.0   # minimum seconds between Frog sounds
BLOW_COOLDOWN = 15.0  # minimum seconds between Blow sounds
STEP_COOLDOWN = 2.0   # minimum seconds between Pop sounds

# Button/Allow detection (see note in Sounds section above)
ORPHAN_DETECTION = False  # set True to enable Blow (off by default — see note)
ORPHAN_TIMEOUT   = 30.0   # raise if you run tools that take longer than this

All sounds are macOS built-in .aiff files from /System/Library/Sounds/. Run this to list them:

ls /System/Library/Sounds/

After editing, apply changes:

launchctl unload ~/Library/LaunchAgents/com.user.copilot-notifier.plist
launchctl load  ~/Library/LaunchAgents/com.user.copilot-notifier.plist

How it works

Watches the VS Code Copilot Chat extension log file for two patterns:

• ccreq:... | success | ... | [panel/editAgent] — agent LLM step (Pop)
• [ToolCallingLoop] Stop hook result: shouldContinue=false — agent turn complete (Frog)

Uses tail -F to follow the log efficiently. Automatically picks up new VS Code windows every 30 seconds.

Manage

# Status
launchctl list | grep copilot

# Logs
tail -f ~/path/to/copilot-notifications/notifier.log

# Stop
launchctl unload ~/Library/LaunchAgents/com.user.copilot-notifier.plist

# Start
launchctl load ~/Library/LaunchAgents/com.user.copilot-notifier.plist