claude-code-sounds

Never miss a Claude Code permission prompt again. This tool adds audio notifications to Claude Code so you hear a sound every time it needs your attention.

The Problem

When using Claude Code, it frequently pauses to ask for permission before running commands, editing files, etc. If you're multitasking or looking at another screen, you can miss these prompts — leaving Claude waiting and wasting your time.

The Solution

claude-code-sounds uses Claude Code's built-in hooks system to play a sound whenever a permission dialog appears. Works on Linux, macOS, and Windows (WSL).

Quick Start

git clone https://github.com/StaticB1/claude-code-sounds.git
cd claude-code-sounds
./install.sh

That's it. Restart Claude Code and you'll hear a chime on every permission prompt.

How It Works

Claude Code supports hooks — shell commands that run in response to specific events. This tool adds a PermissionRequest hook to your ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay ~/.claude/sounds/notification.wav &"
          }
        ]
      }
    ]
  }
}

The & at the end is important — it runs the audio player in the background so it doesn't block Claude Code.

Supported Events

The PermissionRequest event fires whenever Claude Code needs your approval. You can also hook into other events:

Event	When it fires
PermissionRequest	Claude needs permission to run a tool
Stop	Claude finishes its response
Notification	Claude shows a notification
PreToolUse	Before any tool runs
PostToolUse	After a tool completes

Requirements

• Claude Code CLI
• jq (for merging settings)
• An audio player (auto-detected):
  • Linux: paplay, aplay, or ffplay
  • macOS: afplay (built-in)
  • Windows/WSL: powershell.exe

Manual Installation

If you prefer to set it up yourself:

1. Copy the sound file:

mkdir -p ~/.claude/sounds
cp sounds/notification.wav ~/.claude/sounds/

2. Add to your ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay ~/.claude/sounds/notification.wav &"
          }
        ]
      }
    ]
  }
}

Replace aplay with your platform's audio player (afplay on macOS).

3. Restart Claude Code.

Custom Sounds

Replace the sound file at ~/.claude/sounds/notification.wav with any .wav file you like. Or place multiple sound files in ~/.claude/sounds/ and update the command in your settings.

Uninstall

./uninstall.sh

Or manually remove the PermissionRequest hook from ~/.claude/settings.json.

Troubleshooting

No sound plays:

• Make sure your audio player works: aplay ~/.claude/sounds/notification.wav
• Check your system volume
• Restart Claude Code after installing (hooks are loaded at startup)

Hook not firing:

• Verify ~/.claude/settings.json is valid JSON: jq . ~/.claude/settings.json
• Make sure you're using PermissionRequest, not Notification
• Open /hooks in Claude Code to reload config, or restart the session

Contributing

PRs welcome! Ideas:

• More sound themes
• Per-event sounds (different sound for Stop vs PermissionRequest)
• Desktop notification integration
• Volume control

Author

Blessing Siwonde - Statotech Systems

• GitHub: StaticB1

License

MIT