claude-code-hooks-notify

Claude Code Hooks Notify

Sound alerts, desktop notifications, and text-to-speech for Claude Code events — get notified when tasks complete, permissions are needed, or subagents finish.

Features

• Sound alerts — system sounds on macOS, Linux (PulseAudio), and Windows
• Desktop notifications — osascript (macOS), notify-send (Linux), or balloon tips (Windows)
• Text-to-speech — OpenAI TTS API (high quality) or local TTS (say/espeak/SAPI)
• Cross-platform — works on macOS, Linux, and Windows
• Three hook events:
  • Stop — Claude finished a response
  • Notification — permission prompt or waiting for input
  • SubagentStop — a subagent/task completed

Installation

claude plugin install https://github.com/vlazic/claude-code-hooks-notify

That's it. Claude Code handles the rest automatically.

Configuration

Set these environment variables in your shell profile:

• macOS/Linux: ~/.bashrc, ~/.zshrc, or equivalent
• Windows: System Environment Variables, or your PowerShell profile ($PROFILE)

# Required for OpenAI TTS
export OPENAI_API_KEY="sk-..."

Feature Flags

Variable	Default	Description
HOOK_ENABLE_SOUND	false	Play system sounds on events
HOOK_SHOW_NOTIFICATION	false	Show desktop notifications
HOOK_ENABLE_TTS	true	Enable text-to-speech announcements
HOOK_TTS_ENGINE	openai	TTS engine: openai or espeak

OpenAI TTS Settings

Variable	Default	Description
HOOK_OPENAI_MODEL	tts-1	Model (tts-1 or tts-1-hd)
HOOK_OPENAI_VOICE	alloy	Voice: alloy, echo, fable, onyx, nova, shimmer

Espeak Settings (Linux/macOS only)

Variable	Default	Description
HOOK_ESPEAK_VOICE	en-us	Voice/language
HOOK_ESPEAK_SPEED	200	Words per minute

Prerequisites

Required

• Claude Code CLI
• Node.js (included with Claude Code)

Linux

Package	Purpose	Install
pulseaudio-utils	Sound playback (paplay)	sudo apt install pulseaudio-utils
libnotify-bin	Desktop notifications	sudo apt install libnotify-bin
espeak	Free local TTS	sudo apt install espeak
mpv	OpenAI TTS playback	sudo apt install mpv

macOS

Native tools are used automatically: afplay, osascript, say.

For OpenAI TTS: install mpv via brew install mpv.

Windows

Built-in tools are used automatically:

• Sound: System.Media.SoundPlayer via PowerShell
• Notifications: System.Windows.Forms.NotifyIcon balloon tips via PowerShell
• Local TTS: System.Speech.Synthesis.SpeechSynthesizer (SAPI) via PowerShell

For OpenAI TTS: install mpv and ensure it's in your PATH.

How It Works

This is a Claude Code plugin that registers three hooks for lifecycle events:

1. hook-stop.js — plays a completion sound and says "Done in [project]"
2. hook-notification.js — plays an alert sound and announces what's needed (permission, input)
3. hook-subagent-stop.js — plays a message sound and says "Agent done in [project]"

Each hook reads JSON context from stdin (provided by Claude Code), extracts the project name and event details, then triggers the configured combination of sound, notification, and TTS.

All functions fail silently if dependencies are missing — you won't get errors, just no output for that feature.

Hook Input Format

Claude Code passes JSON on stdin to each hook:

{
  "cwd": "/path/to/project",
  "notification_type": "permission_prompt",
  "tool_name": "Bash",
  "subagent_type": "Explore"
}

Managing the Plugin

# Disable without removing
claude plugin disable claude-code-hooks-notify

# Re-enable
claude plugin enable claude-code-hooks-notify

# Update to latest version
claude plugin update claude-code-hooks-notify

# Uninstall
claude plugin uninstall claude-code-hooks-notify

License

MIT