🔔 AI Done Hooks

April 8, 2026 · View on GitHub

Get notified when your AI coding assistant finishes generating code

Tired of staring at your screen waiting for Claude, Cursor, or Windsurf to finish? Get instant audio/visual notifications when AI completes its response.

Inspired by USB-Clawd but software-only - no hardware required!

🎯 Features

🔊 Sound notifications when AI finishes
🗣️ Voice announcements (macOS)
💬 Desktop notifications
⚡ Works with Cursor, Windsurf, Kiro, and other AI IDEs
🎨 Customizable sounds and messages
🚀 Zero dependencies - uses built-in OS features

🚀 Quick Start

For Kiro

Create or edit ~/.kiro/hooks/ai-done.json:

{
  "name": "AI Done Notification",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "afplay /System/Library/Sounds/Glass.aiff"
  }
}

That's it! Next time Kiro finishes, you'll hear a sound.

For Cursor

Create or edit ~/.cursor/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

Restart Cursor or run /reload

For Windsurf

Create or edit ~/.windsurf/settings.json:

{
  "hooks": {
    "onComplete": {
      "command": "afplay /System/Library/Sounds/Glass.aiff"
    }
  }
}

Restart Windsurf

📦 Installation by OS

macOS

Option 1: Simple Sound

# Copy the config
mkdir -p ~/.kiro/hooks
curl -o ~/.kiro/hooks/ai-done.json https://raw.githubusercontent.com/dinakars777/ai-done-hooks/main/configs/kiro-macos-sound.json

Option 2: Voice Announcement

curl -o ~/.kiro/hooks/ai-done.json https://raw.githubusercontent.com/dinakars777/ai-done-hooks/main/configs/kiro-macos-voice.json

Option 3: Desktop Notification + Sound

curl -o ~/.kiro/hooks/ai-done.json https://raw.githubusercontent.com/dinakars777/ai-done-hooks/main/configs/kiro-macos-full.json

Linux

# Install notification sound (if not present)
sudo apt-get install sound-theme-freedesktop

# Copy the config
mkdir -p ~/.kiro/hooks
curl -o ~/.kiro/hooks/ai-done.json https://raw.githubusercontent.com/dinakars777/ai-done-hooks/main/configs/kiro-linux.json

Windows

# Create directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.kiro\hooks"

# Download config
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/dinakars777/ai-done-hooks/main/configs/kiro-windows.json" -OutFile "$env:USERPROFILE\.kiro\hooks\ai-done.json"

🎨 Customization

Change the Sound (macOS)

Available system sounds:

Glass.aiff - Gentle chime (default)
Ping.aiff - Quick ping
Hero.aiff - Triumphant
Submarine.aiff - Sonar ping
Tink.aiff - Metallic tink
Pop.aiff - Bubble pop
Purr.aiff - Soft purr

Browse all: ls /System/Library/Sounds/

Custom Sound File

{
  "name": "AI Done - Custom Sound",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "afplay ~/sounds/my-custom-sound.aiff"
  }
}

Voice Announcements

{
  "name": "AI Done - Voice",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "say 'Code generation complete!'"
  }
}

Fun voice messages:

"say 'Your code is ready, master'"
"say 'Beep boop, task complete'"
"say 'I have finished thinking'"
"say -v Samantha 'All done!'"

Desktop Notification + Sound

{
  "name": "AI Done - Full Notification",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "osascript -e 'display notification \"AI has finished generating code\" with title \"Kiro\" sound name \"Glass\"'"
  }
}

🎯 Advanced Usage

Different Sounds for Success vs Error

Create two hooks:

Success (ai-done-success.json):

{
  "name": "AI Done - Success",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "afplay /System/Library/Sounds/Hero.aiff"
  }
}

Error (ai-done-error.json):

{
  "name": "AI Done - Error",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "afplay /System/Library/Sounds/Basso.aiff"
  }
}

Only Notify for Long Tasks

Add a delay check (requires custom script):

#!/bin/bash
# ~/scripts/notify-if-long.sh
DURATION=\$1
if [ $DURATION -gt 10 ]; then
  afplay /System/Library/Sounds/Glass.aiff
fi

Send to Slack/Discord

{
  "name": "AI Done - Slack",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "curl -X POST -H 'Content-type: application/json' --data '{\"text\":\"AI finished!\"}' YOUR_WEBHOOK_URL"
  }
}

Trigger Physical Device

If you have a smart light or USB device:

{
  "name": "AI Done - Smart Light",
  "version": "1.0.0",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "curl http://192.168.1.100/api/light/flash"
  }
}

🔧 Troubleshooting

Sound Not Playing (macOS)

Check if sound file exists:
```
ls /System/Library/Sounds/Glass.aiff
```

Test sound manually:

afplay /System/Library/Sounds/Glass.aiff

Check permissions:
```
chmod +x ~/.kiro/hooks/ai-done.json
```

Hook Not Triggering

Verify hook file location:
```
ls -la ~/.kiro/hooks/
```
Check JSON syntax:
```
cat ~/.kiro/hooks/ai-done.json | jq .
```
Restart your AI IDE

Linux: No Sound

Install audio player:

# Ubuntu/Debian
sudo apt-get install sox

# Fedora
sudo dnf install sox

# Arch
sudo pacman -S sox

Then use play command instead of afplay.

🎨 Pre-made Configs

All configs are in the configs/ directory:

kiro-macos-sound.json - Simple sound notification
kiro-macos-voice.json - Voice announcement
kiro-macos-full.json - Notification + sound
kiro-linux.json - Linux notification
kiro-windows.json - Windows notification
cursor-macos.json - Cursor on macOS
windsurf-macos.json - Windsurf on macOS

🤝 Contributing

Have a cool notification idea? Submit a PR!

Ideas we'd love to see:

Integration with smart home devices
Haptic feedback (if possible)
Custom notification sounds
Platform-specific optimizations

📝 License

MIT

USB-Clawd - Physical notification device (hardware)
moody - macOS menu bar mood indicator
git-time-machine - Visual git reflog browser

Star this repo if it saves you from staring at loading spinners! ⭐