Sound notifications and alerts for Claude Code tasks
- version
- 1.3.1
- GitHub stars
- 7
Install
/plugin install ping@vibekitRun it inside Claude Code after adding the marketplace with /plugin marketplace add shrwnsan/vibekit-claude-plugins.
Contents
Discovered from sourceAgents 3
Changelog
All notable changes to the Ping Claude Code plugin will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
1.3.0 - 2026-02-13
Added ✨
- Config File Support: New
~/.claude/ping-config.jsonconfiguration file that works with hook events - JSON Schema:
config-schema.jsonfor IDE autocomplete and validation - Config Template:
ping-config.json.examplefor easy setup - Relative Path Support:
soundsDirsupports~/prefix for home directory paths
Changed 🔄
- Priority Order: Config file → Environment variables → Defaults
- Documentation: Restructured README with config file as recommended approach
Fixed 🐛
- Custom sound directories now work with hook events (previously only env vars worked)
1.2.0 - 2026-02-13
Added ✨
- Relative Sound Filenames: Sound files can now be specified relative to
PING_SOUNDS_DIRor using absolute paths - Per-Event Disable: Individual sound events can be disabled by setting them to empty string (
"") ${CLAUDE_PLUGIN_ROOT}Variable: Automatic resolution to plugin installation directory in configuration
Changed 🔄
- Configuration System: Migrated from environment file to
settings.jsonfor better integration with Claude Code - Documentation: Enhanced configuration examples with relative/absolute path options
Configuration ⚙️
PING_SOUND_SESSION_START- Sound for session start event (set to""to disable)PING_SOUND_USER_PROMPT- Sound when Claude needs your input (set to""to disable)PING_SOUND_NOTIFICATION- Sound for general notifications (set to""to disable)PING_SOUND_STOP- Sound when session completes (set to""to disable)
1.0.0 - 2025-12-23
Added ✨
- Initial Release: Sound notifications for Claude Code events
- Four Event Types: Session Start, User Prompt, Notification, Stop
- Cross-Platform Support: macOS (afplay), Linux (paplay/aplay), Windows (PowerShell)
- Default Sounds: Included Warcraft-inspired Peon sounds
- Hook-Based Integration: Uses Claude Code hooks for event detection
Ping
Sound notifications and alerts for Claude Code tasks.
Overview
Ping plays a sound on key Claude Code events through hooks: task completion, input requests, session start and end.
Features
- Session Start - Sound notification when a Claude Code session begins
- User Prompt - Audio alert when Claude needs your input
- Notification - Sound for general notifications
- Stop - Sound when a session completes
Quick start
The Ping plugin is part of the VibeKit marketplace.
- Install via:
claude plugin marketplace add shrwnsan/vibekit-claude-plugins
claude plugin install ping@vibekit
-
Restart Claude Code
-
Sounds will play on session events
The plugin uses built-in OS sounds by default.
Configuration
Create a configuration file at ~/.claude/ping-config.json:
{
"$schema": "https://raw.githubusercontent.com/shrwnsan/vibekit-claude-plugins/main/plugins/ping/config-schema.json",
"soundsDir": "~/custom-sounds",
"sounds": {
"sessionStart": "PeonReady1.wav",
"userPrompt": "PeonYes3.wav",
"notification": "PeonWhat3.wav",
"stop": "PeonBuildingComplete1.wav"
}
}
This approach:
- The config-file sound directory (
soundsDir) works with hook events, unlike thePING_SOUNDS_DIRenvironment variable - Survives plugin updates without reconfiguration
- Supports IDE autocomplete via JSON Schema
See ping-config.json.example for a full template with all options.
Custom sounds
Default sound filenames (used if no config or environment variables are set):
session-start.wav- Session start notificationuser-prompt.wav- User prompt notificationnotification.wav- General notificationstop.wav- Session complete notification
Supported formats: .wav, .aiff (AIFF/AIFC on macOS and Linux), .mp3 and .m4a (macOS only with afplay)
Using Game Sounds
Follow Delba's tip and use nostalgic game sounds. Popular sources:
Warcraft sounds
MyInstants (instant sound buttons):
Platform support
- macOS: Uses
afplaycommand - Linux: Uses
paplay(PulseAudio) oraplay(ALSA) - Windows: Uses PowerShell
Media.SoundPlayer
Recent updates
- v1.3.0: Added config file support (
~/.claude/ping-config.json) that works with hook events, with JSON schema for IDE autocomplete - v1.2.0: Added relative sound filenames, per-event disable, and
${CLAUDE_PLUGIN_ROOT}variable; migrated tosettings.jsonconfiguration - v1.0.0: Initial release with sound notifications for session events
See CHANGELOG.md for version history.
License
Apache 2.0
Acknowledgments
Inspired by Delba Oliveira's tip on using game sounds for Claude Code notifications.
Ping Sounds
Place your custom sound files in this directory.
Expected Files
session-start.wav- Sound played when a Claude Code session startsuser-prompt.wav- Sound played when Claude needs your inputnotification.wav- Sound played for general notificationsstop.wav- Sound played when a session completes
Default Fallback
If no custom sounds are provided, Ping falls back to the system "Glass" sound on macOS (/System/Library/Sounds/Glass.aiff). On Linux and Windows, no system sound fallback is available — sounds will only play if custom sound files are provided.
Game Sounds
Add nostalgic game sounds here! Some classic sources:
- Starcraft unit sounds
- Warcraft acknowledgements
- Mario power-up sounds
- Any game sounds you love
Audio Conversion (macOS)
If you have OGG or other audio formats that need conversion to WAV, macOS has a built-in tool:
afconvert -f WAVE -d LEI16 input.ogg output.wav
To convert all OGG files in the current directory:
for f in *.ogg; do afconvert -f WAVE -d LEI16 "$f" "${f%.ogg}.wav"; done
Sponsors
Details
- Marketplace
- shrwnsan/vibekit-claude-plugins
- Source
- plugins/ping
- Author
- shrwnsan
- Category
- Productivity
- License
- Apache-2.0
- Keywords
- notification, audio, alert, productivity, sound
