Sound alerts for Claude Code and other coding agents

Play a short sound when your coding agent finishes, needs your input, or hits an error, so you can look away from the terminal.

The problem

A coding agent can work for several minutes while you do something else. You either watch the terminal or come back to find it stopped on a question ten minutes ago. A different short sound for done, needs input, and error tells you which one it is without looking.

Three searches to start with

Real tracks from the catalog. Press play to hear up to 30 seconds.

Done

A 0.7-second notification sound, tagged as an interface sound.
Search for "notification sound"
- CreatorAssets UI.
  
  SFX 0.7 s
CC0: no credit required.
Needs your input

A chime about a third of a second long, also tagged as an interface sound.
Search for "chime notification"
- josepharaoh99 UI and foley.
  
  SFX 0.3 s
CC0: no credit required.
Error

A 0.2-second sound with more high frequencies than the other two, so it stands apart.
Search for "error"
- Kenney UI.
  
  SFX 0.2 s
CC0: no credit required.

Add the sounds to Claude Code

Claude Code runs a command when an event happens. These hooks run afplay, the audio player that comes with macOS, on one sound file for each event.

Open each of the three tracks above, export it as WAV, and save the files in the folder ~/.claude/sounds as done.wav, needs-input.wav, and error.wav.
Open ~/.claude/settings.json to hear the sounds in every project, or .claude/settings.json in a project folder to hear them in that project only.
Merge the hooks below into the file. If the file already has a hooks key, add the three events to it.

settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay \"$HOME/.claude/sounds/done.wav\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "afplay \"$HOME/.claude/sounds/needs-input.wav\""
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "rate_limit|overloaded|server_error",
        "hooks": [
          {
            "type": "command",
            "command": "afplay \"$HOME/.claude/sounds/error.wav\""
          }
        ]
      }
    ]
  }
}

Sound files

Event	When it fires	File	Track
`Stop`	Claude finished its turn	`done.wav`	Notification Sound Effects 1
`Notification`	Claude needs permission or is waiting for you	`needs-input.wav`	Chime Notification
`StopFailure`	The turn ended because of an API error	`error.wav`	Error 001

Notes

afplay is a macOS command. On Linux, use a player such as paplay or aplay in the command instead.
The Stop event has no matcher, so it fires after every turn. The Notification matcher limits that event to permission prompts and idle prompts. The StopFailure matcher limits that event to rate limit, overloaded, and server errors.

License

All three sounds are CC0, so you can use them in your own setup, share your settings file, or ship them in a tool without credit.

Ask your AI assistant

Connect Uncommon Ear to Claude, Cursor, or another assistant, then paste this.

Sound alerts for Claude Code and other coding agents

Search Uncommon Ear for three short CC0 sound effects, one for done, one for needs input, and one for error, and add Claude Code hooks that play them with afplay.

Set up your AI assistant