input-sound
A Claude Code plugin that plays a sound when Claude is waiting on you — turn finished, permission prompt, or idle attention notification. Five short tones ship with the plugin; you can also point it at any audio file you like.
Behavior
- Plays once per waiting event. If multiple hooks fire for the same wait (e.g.
PermissionRequest and Notification), you hear one sound, not two — a per-user PID file debounces re-triggers while a player is still alive.
- Stops when you respond.
UserPromptSubmit kills any still-playing sound on your next chat message; PostToolUse does the same when you answer an AskUserQuestion / ExitPlanMode prompt. Mainly matters for longer custom files; bundled tones have already finished by then.
- 3-second post-input cooldown. After any stop event, play requests within the next 3 seconds are suppressed. This avoids the double-beep that would otherwise happen when you answer a mid-turn
AskUserQuestion, Claude emits a short follow-up reply, the turn ends, and Stop fires immediately. You're already paying attention — no need to ping you again.
- Never blocks Claude. The player is spawned via
setsid (or backgrounded on systems without it), the hook script returns immediately, and missing players / missing files exit silently with code 0.
Install
The plugin ships with a tiny local marketplace (.claude-plugin/marketplace.json), so installation is two CLI commands:
# Register this directory as a marketplace (one-time, user scope)
claude plugin marketplace add /absolute/path/to/this/repo
# Install the plugin from that marketplace
claude plugin install input-sound@lajna-local
Default scope is user (~/.claude/settings.json) — enabled across all projects. Use --scope project for a project-scoped install (./.claude/settings.json, shared via git) or --scope local for a personal project install (./.claude/settings.local.json).
Equivalent flow from inside a Claude Code session:
/plugin marketplace add /absolute/path/to/this/repo
/plugin install input-sound@lajna-local
Verify:
claude plugin list # input-sound@lajna-local should show as enabled
Inside Claude Code, /hooks should list the Stop, Notification, and UserPromptSubmit hooks pointing at scripts under ${CLAUDE_PLUGIN_ROOT}.
Configuration
The plugin declares three userConfig fields:
| Field | Type | Default | Notes |
|---|
sound | string | bell | One of bell, chime, ding, pop, blip. Invalid names fall back to bell. |
custom_sound_file | file path | (empty) | Absolute path to your own audio file. When set, takes precedence over sound. |
enabled | boolean | true | Mute without uninstalling. |
The userConfig schema doesn't support enum/dropdown fields, so sound is free-text — typo-safe via the bell fallback.
Edit values via the interactive plugin manager (/plugin inside Claude Code → select input-sound → edit config), or write them directly into ~/.claude/settings.json under the relevant plugin config block.
Bundled sounds
| Name | Length | Character |
|---|
bell | 0.35s | Warm 880 Hz bell with a 1760 Hz overtone. The default. |
chime | 0.45s | Brighter 1320 Hz + 1980 Hz pairing, slightly longer release. |
ding | 0.30s | Single 1760 Hz sine, short. |
pop | 0.08s | Quick low-frequency blip. |
blip | 0.12s | Two-tone snap at 660 + 1320 Hz. |
All are 16-bit mono WAV at 22.05 kHz, 3.5–20 KB each. Generated by scripts/_generate_sounds.py — re-run it to tweak frequencies, lengths, or envelopes.
Custom sound constraints
Format support depends on the player picked at runtime:
| Platform | Player(s) probed | Formats |
|---|
| Linux | paplay → pw-play → aplay → play | WAV always works. FLAC/OGG via PulseAudio/PipeWire. MP3 only if play (sox) is selected — but earlier players are probed first, so don't rely on it. |
| macOS | afplay | WAV, AIFF, MP3, M4A/AAC. |
| Windows | powershell.exe (Git Bash / WSL / Cygwin) | WAV only (System.Media.SoundPlayer). |
→ Use WAV for portability. MP3 will fail silently on Windows and on Linux setups without sox.
Path requirements:
- Absolute paths only. Relative paths resolve against
${CLAUDE_PROJECT_DIR}, which changes per session.
- No
~ expansion. Write /home/you/sounds/foo.wav, not ~/sounds/foo.wav.
- Must be readable by the user running Claude Code.
- Spaces in paths are fine — the script quotes everything.
Behavioral limits:
- No looping. The file plays once; encode any repetition into the file itself.
- No length cap. A long file plays until it ends or until you submit a prompt.
- No volume control — uses the system default.
- Debounce suppresses additional beeps while a player is alive. With a long custom file, you won't get a second sound for new
Notification events until the first finishes or you respond.
