{
  "markdown": "# bells-and-whistles\n\nA Claude Code plugin that plays notification sounds when your agent finishes\nworking or needs your attention. Because staring at a terminal, waiting, is no\nway to live.\n\n## What it does\n\nClaude Code fires two events you care about: **Stop** (the agent finished) and\n**Notification** (it wants permission or has a question). This plugin intercepts\nboth and plays a sound. Optionally, it speaks too — \"Job completed!\" or \"Hey!\nBack to work!\" — so you can keep your eyes on the other monitor, guilt-free.\n\n## Themes\n\nPick one. You will not be quizzed.\n\n| Theme | Flavor |\n|---|---|\n| **Videogame** | Zelda secrets, Mario coins, MGS alerts, FF victory fanfares |\n| **Disney** | \"When You Wish Upon a Star,\" \"Let It Go,\" and eight more you already know by heart |\n| **Anime** | Evangelion brass, Sailor Moon transformations, Cowboy Bebop jazz stabs |\n| **Movies** | Star Wars, Jaws, the Imperial March — the whole cinema lobby |\n| **90s Rock** | Smoke on the Water, Enter Sandman, Seven Nation Army riffs in pure sine waves |\n| **Classical** | Beethoven's Fifth, Fur Elise, Ride of the Valkyries |\n| **Beeps** | Clean, professional tones for people who attend stand-ups with their camera on |\n| **Chirps** | Robins, canaries, chickadees — an aviary in your terminal |\n| **Cyberpunk 2077** | Neon drones, netrunner arpeggios, corpo alerts — Night City in sine waves |\n| **D&D / Fantasy** | Tavern lutes, quest fanfares, spell casts — roll for initiative |\n\nEach theme contains 10 short melodies. The plugin picks one at random, so\nrepetition stays tolerable.\n\n## Voice\n\nVoice announcements use **AWS Polly** (Stephen, Tiffany, Brian, or Amy).\nIf you run tmux, the voice tells you *which window* finished — useful when you\nhave six agents running and zero idea which one just spoke up.\n\nVoice is optional. The plugin ships pre-generated WAV files and works fine\nwithout AWS credentials.\n\n### Themed phrases\n\nThe Cyberpunk and D&D themes include themed speech phrases — \"Flatline\ncomplete, choom!\" instead of \"Job completed!\" Themed phrases are selected\nrandomly from a pool, so you get variety.\n\nYou can choose between themed and standard phrases during configuration. Edit\n`speech_phrases.json` to customize or add your own phrases, then regenerate\nwith `generate_sounds.py`.\n\n### ElevenLabs (alternative TTS)\n\nYou can use [ElevenLabs](https://elevenlabs.io) instead of AWS Polly to\ngenerate speech with any voice from their library. ElevenLabs is a\ngeneration-time alternative — at runtime the plugin just plays WAV files\nregardless of which provider generated them.\n\nTo generate speech with ElevenLabs:\n\n```bash\n# Using --api-key flag\npython3 generate_sounds.py --speech-only --tts-provider elevenlabs \\\n    --api-key YOUR_KEY --voice-id YOUR_VOICE_ID --accent us --gender male\n\n# Or using environment variable\nexport ELEVENLABS_API_KEY=your_key\npython3 generate_sounds.py --speech-only --tts-provider elevenlabs \\\n    --voice-id YOUR_VOICE_ID --accent us --gender male\n```\n\nThe `--accent` and `--gender` flags determine which speech slot to overwrite\n(for standard phrases) and which voice to select from the config mapping (if\n`--voice-id` is not provided). For themed phrases, the output always goes to\n`sounds/speech/themed/{theme}/`.\n\nYou can also configure a voice mapping in `config.json` so you don't need\n`--voice-id` each time:\n\n```json\n{\n  \"elevenlabs_voices\": {\n    \"us\": {\"male\": \"voice_id_1\", \"female\": \"voice_id_2\"},\n    \"uk\": {\"male\": \"voice_id_3\"}\n  }\n}\n```\n\nElevenLabs requires `ffmpeg` for MP3→WAV conversion.\n\n## Installation\n\nInstall from the Groundwork Marketplace. Add the marketplace once:\n\n```\nclaude plugin marketplace add etr/groundwork-marketplace\n```\n\nThen install the plugin:\n\n```\nclaude plugin install bells-and-whistles@groundwork-marketplace\n```\n\nRun the built-in setup command to choose your theme, mode, and voice:\n\n```\n/configure-bells-and-whistles\n```\n\nThat writes a `config.json` in the plugin root and cleans up any old hook\nconfigurations.\n\nTo update later:\n\n```\nclaude plugin update bells-and-whistles@groundwork-marketplace\n```\n\n### Manual installation\n\nIf you prefer to clone the repo yourself:\n\n```\nclaude plugins add /path/to/bells-and-whistles\n```\n\n## Muting\n\nSilence notifications without changing your configuration:\n\n```\n/mute          # mute globally (or choose scope if in tmux)\n/mute all      # mute all tabs\n/mute tab      # mute just the current tmux window\n```\n\n```\n/unmute        # unmute (auto-detects what's muted)\n/unmute all    # unmute everything\n/unmute tab    # unmute just the current tmux window\n```\n\nPer-tab mute requires tmux. Mute state persists until you unmute or delete the\nmarker files (`.mute_all`, `.mute_window_*`) from the plugin root.\n\n## Configuration\n\nEdit `config.json` directly if you prefer:\n\n```json\n{\n  \"mode\": \"sound_and_voice\",\n  \"accent\": \"us\",\n  \"gender\": \"male\",\n  \"voice_style\": \"full_sentence\",\n  \"theme\": \"cyberpunk\",\n  \"use_themed_phrases\": true\n}\n```\n\n**mode** — `sound_and_voice`, `sound_only`, or `voice_only`\n\n**accent** — `us` or `uk` (used for standard phrases; ignored when `use_themed_phrases` is true)\n\n**gender** — `male` or `female` (used for standard phrases; ignored when `use_themed_phrases` is true)\n\n**voice_style** — `full_sentence` or `number_only`\n\n**theme** — one of: `videogame`, `disney`, `anime`, `movies`, `90s_rock`,\n`classical`, `beeps`, `chirps`, `cyberpunk`, `dnd`\n\n**use_themed_phrases** — `true` to use themed speech phrases (if available for\nthe selected theme), `false` to use standard \"Job completed!\" phrases\n\n## Customizing phrases\n\nSpeech phrases live in `speech_phrases.json`. Each theme can define its own\nphrases for `stop`, `notification`, `stop_window`, and `notification_window`\nevents. The `{window}` placeholder in window templates is replaced with the\ntmux window number (0-9) at generation time.\n\nAfter editing `speech_phrases.json`, regenerate speech files:\n\n```bash\npython3 generate_sounds.py --speech-only\n```\n\n## Platform support\n\n| Platform | Playback method |\n|---|---|\n| WSL | `powershell.exe` via `System.Media.SoundPlayer` |\n| macOS | `afplay` |\n| Linux | `aplay`, falling back to `paplay` |\n| SSH | Terminal bell (`\\a`) — dignity preserved |\n\n## Regenerating sounds\n\nThe pre-generated WAV files live in `sounds/`. To regenerate melodies (no\ndependencies beyond Python 3):\n\n```\npython3 generate_sounds.py --melodies-only\n```\n\nTo regenerate speech files (requires AWS CLI with Polly access):\n\n```\npython3 generate_sounds.py --speech-only\n```\n\nYou can narrow the scope with `--theme`, `--accent`, and `--gender`.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Special Thanks\n- https://github.com/jackmarketon for Elevenlabs integration, D&D/Cyberpunk audio, and configurable phrases.\n",
  "bytes": 6748,
  "sha": "7ab6a9242f4a119ac9d185ebbaf6c55c95760e53e8ca3c69b9b8f8269d436d0b",
  "repo_slug": "etr/bells-and-whistles",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_etr_bells_and_whistles_bells_and_whistle_348cd363/readme"
}