Configure notification sounds and settings for claude-notifications plugin
Interactive wizard to configure notification sounds for task completion, reviews, questions, and plans. Choose from built-in or system sounds with live preview capability.
/plugin marketplace add 777genius/claude-notifications-go/plugin install claude-notifications-go@claude-notifications-goWelcome! This interactive wizard will help you configure notification sounds for Claude Code.
Let's make your Claude experience more delightful with custom audio notifications!
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
IMPORTANT FOR CLAUDE:
This setup wizard is INTERACTIVE. Users can preview sounds at ANY time by saying:
Your job:
${PLUGIN_ROOT}/bin/sound-preview <path> to play itFlow:
Be patient and encouraging - sound selection is personal!
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
First, let me verify the notification binary is installed:
# Get plugin root directory
# Priority: 1) CLAUDE_PLUGIN_ROOT env var, 2) installed plugin location, 3) current directory
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
# Try the standard installed plugin location
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
# Fallback to current directory (for development)
PLUGIN_ROOT="$(pwd)"
fi
fi
echo "Plugin root: $PLUGIN_ROOT"
echo ""
# Check if binary exists (platform-agnostic check)
BINARY_EXISTS=false
if [ -f "${PLUGIN_ROOT}/bin/claude-notifications" ] || \
[ -f "${PLUGIN_ROOT}/bin/claude-notifications-darwin-amd64" ] || \
[ -f "${PLUGIN_ROOT}/bin/claude-notifications-darwin-arm64" ] || \
[ -f "${PLUGIN_ROOT}/bin/claude-notifications-linux-amd64" ] || \
[ -f "${PLUGIN_ROOT}/bin/claude-notifications-windows-amd64.exe" ]; then
BINARY_EXISTS=true
fi
if [ "$BINARY_EXISTS" = "false" ]; then
echo "β οΈ Notification binary not found. Installing..."
echo ""
if ! "${PLUGIN_ROOT}/bin/install.sh"; then
echo ""
echo "β Error: Failed to install notification binary"
echo "Please run /claude-notifications-go:notifications-init or check your internet connection"
exit 1
fi
echo ""
echo "β
Binary installed successfully!"
echo ""
else
echo "β
Notification binary is already installed"
echo ""
fi
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Now let me detect what sound options are available on your system!
# Get plugin root (re-declare for this bash session)
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
PLUGIN_ROOT="$(pwd)"
fi
fi
# Detect Operating System
OS_TYPE=$(uname -s)
case "$OS_TYPE" in
Darwin*)
echo "Operating System: macOS"
HAS_SYSTEM_SOUNDS="true"
SYSTEM_SOUNDS_DIR="/System/Library/Sounds"
;;
Linux*)
echo "Operating System: Linux"
if [ -d "/usr/share/sounds" ]; then
HAS_SYSTEM_SOUNDS="true"
SYSTEM_SOUNDS_DIR="/usr/share/sounds"
else
HAS_SYSTEM_SOUNDS="false"
fi
;;
MINGW*|MSYS*|CYGWIN*)
echo "Operating System: Windows"
HAS_SYSTEM_SOUNDS="false"
;;
*)
echo "Operating System: Unknown"
HAS_SYSTEM_SOUNDS="false"
;;
esac
# Built-in Sounds
echo ""
echo "Built-in sounds (included with plugin):"
if [ -d "${PLUGIN_ROOT}/sounds" ]; then
ls -1 "${PLUGIN_ROOT}/sounds/"*.mp3 2>/dev/null | while read file; do
name=$(basename "$file" .mp3)
echo " β $name.mp3"
done
else
echo " Warning: sounds/ directory not found!"
fi
# System Sounds
if [ "$HAS_SYSTEM_SOUNDS" = "true" ]; then
echo ""
echo "System sounds detected at: $SYSTEM_SOUNDS_DIR"
case "$OS_TYPE" in
Darwin*)
# macOS system sounds
echo "Available macOS system sounds:"
ls -1 /System/Library/Sounds/*.aiff 2>/dev/null | while read file; do
name=$(basename "$file" .aiff)
echo " β’ $name"
done
;;
Linux*)
# Linux system sounds (varies by distribution)
echo "Available Linux system sounds (sample):"
find /usr/share/sounds -type f \( -name "*.ogg" -o -name "*.wav" \) 2>/dev/null | head -10 | while read file; do
name=$(basename "$file")
echo " β’ $name"
done
;;
esac
else
echo ""
echo "β οΈ No system sounds detected on this platform."
echo " Don't worry! You can use the built-in MP3 sounds included with the plugin."
echo " They work perfectly on all platforms!"
fi
Always available:
macOS system sounds (if detected):
Linux system sounds (if detected):
/usr/share/sounds/ββββββββββββββββββββββββββββββββββββββββββββββββββββ
CRITICAL INSTRUCTION FOR CLAUDE:
Before asking the user to make final choices, you MUST offer to play sounds for them.
Tell the user:
π΅ Want to hear sounds before choosing? I can play any sound for you! Just say:
"play task-complete"- Built-in task-complete sound"play Glass"- macOS Glass system sound"preview Hero"- Preview any available soundTry as many as you like! When you're ready, I'll ask you to select sounds for each notification type.
How to handle preview requests:
When user says "play [sound_name]", "preview [sound_name]", "ΠΏΡΠΎΡΠ»ΡΡΠ°ΡΡ [sound_name]", or "ΠΏΡΠΎΠΈΠ³ΡΠ°ΡΡ [sound_name]":
Extract sound name from user message (ignore the command word, keep only the sound name)
Determine the full path to the sound file:
# Get plugin root
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
PLUGIN_ROOT="$(pwd)"
fi
fi
# For built-in sounds (no extension needed)
if [[ "$sound_name" == "task-complete" ]] || [[ "$sound_name" == "review-complete" ]] || [[ "$sound_name" == "question" ]] || [[ "$sound_name" == "plan-ready" ]]; then
SOUND_PATH="${PLUGIN_ROOT}/sounds/${sound_name}.mp3"
# For macOS system sounds
elif [[ -f "/System/Library/Sounds/${sound_name}.aiff" ]]; then
SOUND_PATH="/System/Library/Sounds/${sound_name}.aiff"
# Try common variations
elif [[ -f "/System/Library/Sounds/${sound_name}.mp3" ]]; then
SOUND_PATH="/System/Library/Sounds/${sound_name}.mp3"
else
echo "β Sound '${sound_name}' not found. Available options listed above."
exit 1
fi
Play the sound using the sound-preview utility with reduced volume:
# Get plugin root
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
PLUGIN_ROOT="$(pwd)"
fi
fi
echo "π Playing: ${sound_name}... (volume: 30%)"
"${PLUGIN_ROOT}/bin/sound-preview" --volume 0.3 "$SOUND_PATH"
echo "β Playback complete!"
IMPORTANT: Always use --volume 0.3 (30% volume) when previewing sounds during setup to avoid disturbing the user with loud sounds.
Ask if they want to hear more:
Would you like to:
- Hear another sound? (just type "play [name]")
- Ready to make your selections? (type "ready")
Examples of user interactions:
User: play Glass
Claude: [runs bin/sound-preview --volume 0.3 /System/Library/Sounds/Glass.aiff]
Claude: "π Playing: Glass... (volume: 30%) β Playback complete! Would you like to hear another sound, or ready to choose?"
User: preview task-complete
Claude: [runs bin/sound-preview --volume 0.3 sounds/task-complete.mp3]
Claude: "π Playing: task-complete... (volume: 30%) β Playback complete!"
User: ΠΏΡΠΎΡΠ»ΡΡΠ°ΡΡ Hero
Claude: [runs bin/sound-preview --volume 0.3 /System/Library/Sounds/Hero.aiff]
Claude: "π Playing: Hero... (volume: 30%) β Playback complete!"
User: ΠΏΡΠΎΠΈΠ³ΡΠ°ΡΡ Ping
Claude: [runs bin/sound-preview --volume 0.3 /System/Library/Sounds/Ping.aiff]
Claude: "π Playing: Ping... (volume: 30%) β Playback complete!"
User: ready
Claude: "Great! Let's configure your notification sounds..."
[proceeds to Questions 1-4]
Edge cases:
User: play unknown-sound
Claude: "β Sound 'unknown-sound' not found. Available sounds are:
Built-in: task-complete, review-complete, question, plan-ready
System (macOS): Glass, Hero, Funk, Sosumi, Ping, Purr, Basso, etc.
Try: 'play Glass' or 'preview task-complete'"
User: I want Glass for everything
Claude: "Great choice! Let me confirm - you want Glass for all notification types?
Or would you like to choose different sounds for each type?
(You can still preview other sounds if you'd like)"
IMPORTANT:
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Now let's configure your notification sounds! I'll ask you 4 questions - one for each notification type.
IMPORTANT: Build the options list dynamically based on what's available:
# Build options array based on OS and available sounds
OPTIONS=""
# Always include built-in sounds (available on all platforms)
OPTIONS="${OPTIONS}Built-in: task-complete.mp3|Triumphant completion chime (recommended)\n"
OPTIONS="${OPTIONS}Built-in: review-complete.mp3|Gentle notification tone\n"
OPTIONS="${OPTIONS}Built-in: question.mp3|Attention sound\n"
OPTIONS="${OPTIONS}Built-in: plan-ready.mp3|Professional tone\n"
# Add system sounds if available
if [ "$HAS_SYSTEM_SOUNDS" = "true" ] && [ "$OS_TYPE" = "Darwin"* ]; then
# macOS system sounds
OPTIONS="${OPTIONS}System: Glass|Crisp macOS Glass sound\n"
OPTIONS="${OPTIONS}System: Hero|Triumphant fanfare\n"
OPTIONS="${OPTIONS}System: Funk|Distinctive funk groove\n"
OPTIONS="${OPTIONS}System: Sosumi|Pleasant macOS notification\n"
OPTIONS="${OPTIONS}System: Ping|Subtle ping sound\n"
OPTIONS="${OPTIONS}System: Purr|Gentle purr\n"
fi
echo "Available sound options built: $(echo -e "$OPTIONS" | wc -l) options"
Before presenting the question, remind the user:
π΅ Reminder: You can still preview sounds! Just say "play [sound_name]" before making your choice.
When Claude finishes a task, which sound would you like to hear?
Use AskUserQuestion with dynamically generated options:
If macOS with system sounds:
If Linux/Windows (no system sounds):
Note: System sounds are only available on macOS. On other platforms, use the built-in MP3 sounds which work perfectly everywhere!
CRITICAL: If user says "play [sound]" instead of choosing, DO NOT call AskUserQuestion yet. First play the sound, then re-ask the question.
Before presenting the question, remind the user:
π΅ Reminder: You can preview sounds! Just say "play [sound_name]" before choosing.
When Claude completes a code review or analysis, which sound?
Use AskUserQuestion with the same dynamically generated options as Question 1.
Before presenting the question, remind the user:
π΅ Reminder: You can preview sounds! Just say "play [sound_name]" before choosing.
When Claude has a question or needs clarification?
Use AskUserQuestion with the same dynamically generated options as Question 1.
Before presenting the question, remind the user:
π΅ Reminder: You can preview sounds! Just say "play [sound_name]" before choosing.
When Claude finishes planning and is ready for your review?
Use AskUserQuestion with the same dynamically generated options as Question 1.
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Now let's configure the volume for your notification sounds.
Use AskUserQuestion with:
Volume mapping:
1.00.70.50.30.1Important: Parse the user's choice and extract the numeric value (e.g., "70%" β 0.7).
Note: You can offer to preview a sound at the selected volume:
# Get plugin root
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
PLUGIN_ROOT="$(pwd)"
fi
fi
echo "Let me play a quick test at your selected volume..."
"${PLUGIN_ROOT}/bin/sound-preview" --volume <selected_volume> "${PLUGIN_ROOT}/sounds/task-complete.mp3"
echo "How does that sound? (If you want to adjust, just let me know)"
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Do you want to send notifications to a webhook (Slack, Discord, Telegram)?
Use AskUserQuestion with:
If webhook is enabled, I'll create a placeholder configuration that you can edit later.
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Based on your answers, I'll create config/config.json:
Sound Path Construction (Important!):
Parse the user's choice and construct the correct path:
# Function to convert user choice to file path
get_sound_path() {
local choice="$1"
# Check if it's a built-in sound
if [[ "$choice" == "Built-in:"* ]] || [[ "$choice" == *".mp3" ]]; then
# Extract filename
filename=$(echo "$choice" | sed 's/Built-in: //' | sed 's/^[^:]*: //')
echo "\${CLAUDE_PLUGIN_ROOT}/sounds/${filename}"
# Check if it's a system sound (macOS)
elif [[ "$choice" == "System:"* ]]; then
# Extract sound name (e.g., "Glass" from "System: Glass")
soundname=$(echo "$choice" | sed 's/System: //' | awk '{print $1}')
echo "/System/Library/Sounds/${soundname}.aiff"
# Fallback to built-in if parsing fails
else
echo "\${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3"
fi
}
# Example usage:
TASK_COMPLETE_PATH=$(get_sound_path "$user_answer_1")
REVIEW_COMPLETE_PATH=$(get_sound_path "$user_answer_2")
QUESTION_PATH=$(get_sound_path "$user_answer_3")
PLAN_READY_PATH=$(get_sound_path "$user_answer_4")
Examples:
${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3/System/Library/Sounds/Glass.aiffConfiguration Template:
IMPORTANT - Webhook Configuration Rules:
"enabled": false and "preset": "custom" (DO NOT use "none")"enabled": true and "preset": "slack""enabled": true and "preset": "discord""enabled": true and "preset": "telegram""enabled": true and "preset": "custom"{
"notifications": {
"desktop": {
"enabled": true,
"sound": true,
"volume": <user's selected volume>,
"appIcon": "${CLAUDE_PLUGIN_ROOT}/claude_icon.png"
},
"webhook": {
"enabled": <true if webhook selected, false for "No webhooks">,
"preset": "<slack|discord|telegram|custom - NEVER use 'none', use 'custom' if No webhooks>",
"url": "<placeholder - user must edit>",
"chat_id": "<for telegram only>",
"format": "json",
"headers": {}
},
"suppressQuestionAfterTaskCompleteSeconds": 7
},
"statuses": {
"task_complete": {
"title": "β
Task Completed",
"sound": "<user's choice>",
"keywords": ["completed", "done", "finished", "ΡΡΠΏΠ΅ΡΠ½ΠΎ", "Π·Π°Π²Π΅ΡΡΠ΅Π½"]
},
"review_complete": {
"title": "π Review Completed",
"sound": "<user's choice>",
"keywords": ["review", "ΡΠ΅Π²ΡΡ", "analyzed", "ΠΏΡΠΎΠ²Π΅ΡΠΊΠ°", "analysis"]
},
"question": {
"title": "β Claude Has Questions",
"sound": "<user's choice>",
"keywords": ["question", "Π²ΠΎΠΏΡΠΎΡ", "clarify"]
},
"plan_ready": {
"title": "π Plan Ready for Review",
"sound": "<user's choice>",
"keywords": ["plan", "ΠΏΠ»Π°Π½", "strategy"]
}
}
}
Write this to: ${PLUGIN_ROOT}/config/config.json
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
After creating the configuration, show the user:
π Configuration Saved Successfully!
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Summary:
β
Task Complete β <chosen sound>
π Review Complete β <chosen sound>
β Question β <chosen sound>
π Plan Ready β <chosen sound>
π Desktop notifications: ENABLED
π Volume: <selected volume>%
π Webhooks: <ENABLED/DISABLED>
Configuration file: config/config.json
Ask user: "Would you like to test your task-complete notification now?"
If yes:
# Get plugin root
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
if [ -z "$PLUGIN_ROOT" ]; then
INSTALLED_PATH="$HOME/.claude/plugins/marketplaces/claude-notifications-go"
if [ -d "$INSTALLED_PATH" ]; then
PLUGIN_ROOT="$INSTALLED_PATH"
else
PLUGIN_ROOT="$(pwd)"
fi
fi
echo "Testing task-complete sound at your configured volume (<selected_volume>%)..."
"${PLUGIN_ROOT}/bin/sound-preview" --volume <selected_volume> "<path-to-chosen-sound>"
echo "β Sound test complete!"
Note: This test uses your configured volume level. The actual notifications will use this same volume.
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Editing Later:
/claude-notifications-go:notifications-settings anytime to reconfigureconfig/config.jsonWebhook Configuration:
If you enabled webhooks, you'll need to manually edit config/config.json to add:
Sound Formats Supported:
System Sounds:
/System/Library/Sounds/*.aiff/usr/share/sounds/**/*.ogg (varies by distribution)ββββββββββββββββββββββββββββββββββββββββββββββββββββ
β¨ Sound Selection Tips:
π― Recommended Combinations:
Minimal Setup:
Power User Setup:
Built-in Sounds:
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
Ready to begin? Let's start by choosing your sound source! π΅