bells-and-whistles
A Claude Code plugin that plays notification sounds when your agent finishes
working or needs your attention. Because staring at a terminal, waiting, is no
way to live.
What it does
Claude Code fires two events you care about: Stop (the agent finished) and
Notification (it wants permission or has a question). This plugin intercepts
both and plays a sound. Optionally, it speaks too — "Job completed!" or "Hey!
Back to work!" — so you can keep your eyes on the other monitor, guilt-free.
Themes
Pick one. You will not be quizzed.
| Theme | Flavor |
|---|
| Videogame | Zelda secrets, Mario coins, MGS alerts, FF victory fanfares |
| Disney | "When You Wish Upon a Star," "Let It Go," and eight more you already know by heart |
| Anime | Evangelion brass, Sailor Moon transformations, Cowboy Bebop jazz stabs |
| Movies | Star Wars, Jaws, the Imperial March — the whole cinema lobby |
| 90s Rock | Smoke on the Water, Enter Sandman, Seven Nation Army riffs in pure sine waves |
| Classical | Beethoven's Fifth, Fur Elise, Ride of the Valkyries |
| Beeps | Clean, professional tones for people who attend stand-ups with their camera on |
| Chirps | Robins, canaries, chickadees — an aviary in your terminal |
| Cyberpunk 2077 | Neon drones, netrunner arpeggios, corpo alerts — Night City in sine waves |
| D&D / Fantasy | Tavern lutes, quest fanfares, spell casts — roll for initiative |
Each theme contains 10 short melodies. The plugin picks one at random, so
repetition stays tolerable.
Voice
Voice announcements use AWS Polly (Stephen, Tiffany, Brian, or Amy).
If you run tmux, the voice tells you which window finished — useful when you
have six agents running and zero idea which one just spoke up.
Voice is optional. The plugin ships pre-generated WAV files and works fine
without AWS credentials.
Themed phrases
The Cyberpunk and D&D themes include themed speech phrases — "Flatline
complete, choom!" instead of "Job completed!" Themed phrases are selected
randomly from a pool, so you get variety.
You can choose between themed and standard phrases during configuration. Edit
speech_phrases.json to customize or add your own phrases, then regenerate
with generate_sounds.py.
ElevenLabs (alternative TTS)
You can use ElevenLabs instead of AWS Polly to
generate speech with any voice from their library. ElevenLabs is a
generation-time alternative — at runtime the plugin just plays WAV files
regardless of which provider generated them.
To generate speech with ElevenLabs:
# Using --api-key flag
python3 generate_sounds.py --speech-only --tts-provider elevenlabs \
--api-key YOUR_KEY --voice-id YOUR_VOICE_ID --accent us --gender male
# Or using environment variable
export ELEVENLABS_API_KEY=your_key
python3 generate_sounds.py --speech-only --tts-provider elevenlabs \
--voice-id YOUR_VOICE_ID --accent us --gender male
The --accent and --gender flags determine which speech slot to overwrite
(for standard phrases) and which voice to select from the config mapping (if
--voice-id is not provided). For themed phrases, the output always goes to
sounds/speech/themed/{theme}/.
You can also configure a voice mapping in config.json so you don't need
--voice-id each time:
{
"elevenlabs_voices": {
"us": {"male": "voice_id_1", "female": "voice_id_2"},
"uk": {"male": "voice_id_3"}
}
}
ElevenLabs requires ffmpeg for MP3→WAV conversion.
Installation
Install from the Groundwork Marketplace. Add the marketplace once:
claude plugin marketplace add etr/groundwork-marketplace
Then install the plugin:
claude plugin install bells-and-whistles@groundwork-marketplace
Run the built-in setup command to choose your theme, mode, and voice:
/configure-bells-and-whistles
That writes a config.json in the plugin root and cleans up any old hook
configurations.
To update later:
claude plugin update bells-and-whistles@groundwork-marketplace
Manual installation
If you prefer to clone the repo yourself:
claude plugins add /path/to/bells-and-whistles
Muting
Silence notifications without changing your configuration:
/mute # mute globally (or choose scope if in tmux)
/mute all # mute all tabs
/mute tab # mute just the current tmux window
/unmute # unmute (auto-detects what's muted)
/unmute all # unmute everything
/unmute tab # unmute just the current tmux window
Per-tab mute requires tmux. Mute state persists until you unmute or delete the
marker files (.mute_all, .mute_window_*) from the plugin root.
Configuration
Edit config.json directly if you prefer:
{
"mode": "sound_and_voice",
"accent": "us",
"gender": "male",
"voice_style": "full_sentence",
"theme": "cyberpunk",
"use_themed_phrases": true
}