Sound notifications and alerts for Claude Code tasks

version
1.3.1
GitHub stars
7

Install

/plugin install ping@vibekit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add shrwnsan/vibekit-claude-plugins.

Contents

Discovered from source

Agents 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.json configuration file that works with hook events
  • JSON Schema: config-schema.json for IDE autocomplete and validation
  • Config Template: ping-config.json.example for easy setup
  • Relative Path Support: soundsDir supports ~/ 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_DIR or 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.json for 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.

  1. Install via:
claude plugin marketplace add shrwnsan/vibekit-claude-plugins

claude plugin install ping@vibekit
  1. Restart Claude Code

  2. 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 the PING_SOUNDS_DIR environment 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 notification
  • user-prompt.wav - User prompt notification
  • notification.wav - General notification
  • stop.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 afplay command
  • Linux: Uses paplay (PulseAudio) or aplay (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 to settings.json configuration
  • 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 starts
  • user-prompt.wav - Sound played when Claude needs your input
  • notification.wav - Sound played for general notifications
  • stop.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

More from shrwnsan/vibekit-claude-plugins

All 6