Claude Code notification sound: play one when it finishes, change it, or turn it off

Option 1: the terminal bell

By default Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In any other terminal, this setting makes it ring the terminal bell instead when it finishes or waits for you:

{ "preferredNotifChannel": "terminal_bell" }

• The sound is your terminal's bell, so it is set, and can be muted, in the terminal's own settings.
• Apple Terminal: Claude Code's first-run terminal setup turns the audible bell off in your profile. Turn it back on under Settings > Profiles > Advanced > "Audible bell".
• VS Code's integrated terminal plays the bell sound only when its accessibility.signals.terminalBell setting allows it; the fix is below. A hook plays no matter which terminal you use, and anotifier in VS Code covers the ready-made one.
• The bell travels over SSH to the terminal you are sitting at.

Option 2: a hook with one sound for "done", another for "needs you"

Hooks run alongside Claude Code's built-in notification. Stop fires when Claude finishes a turn; Notification fires when it needs you. This macOS example plays Glass when Claude is done and Ping when it is waiting:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Ping.aiff"
          }
        ]
      }
    ]
  }
}

On Windows, the hook calls PowerShell. In settings.json the backslashes are escaped:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\chimes.wav').PlaySync()\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\notify.wav').PlaySync()\""
          }
        ]
      }
    ]
  }
}

Pick a sound per event

Claude Code has more hook events than Stop and Notification. These are the ones worth a sound. Each event is its own entry in settings.json, so each can play its own file:

To hear the moment Claude asks for permission, use PermissionRequest: the permission_prompt notification only arrives after the six-second wait. This setup plays Glass for done, Sosumi for an approval, and Tink for the idle reminder:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff",
            "async": true
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Sosumi.aiff",
            "async": true
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Tink.aiff",
            "async": true
          }
        ]
      }
    ]
  }
}

Only some notifications

A hook without a matcher plays for every notification type, including ones that don't need you. To sound only for approvals, add "matcher": "permission_prompt" to the entry. The permission notifications guide lists every type and when it fires.

Native Windows and WSL

On native Windows, Claude Code runs a hook command with Git Bash, or with PowerShell when Git Bash isn't installed. The powershell.exe -Command form above works under either. To skip the nested powershell.exe and the quote escaping, set "shell": "powershell" on the hook and write the PowerShell directly:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\chimes.wav').PlaySync()",
            "async": true
          }
        ]
      }
    ]
  }
}

Inside WSL, Claude Code runs the hook in Linux, so afplay isn't there and paplay needs a Linux audio setup. Call Windows PowerShell through Windows interop instead, with a Windows path, so the sound plays on the Windows side. Claude Code's hooks guide notes that powershell.exe must be on your PATH through interop. The same command works as it is:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\tada.wav').PlaySync()\"",
            "async": true
          }
        ]
      }
    ]
  }
}

• SoundPlayer plays .wav files only. Those in C:\Windows\Media are fine; an .mp3 needs a different player.
• In Windows Terminal, preferredNotifChannel set to terminal_bell makes the bell do whatever its bellStyle says: audible is the default and none is silent. With all, the sound plays only while the window has focus; otherwise only the taskbar icon flashes. bellSound picks the file.
• Windows and WSL toast notifications covers the toast side, which takes a different road on each.

Linux: paplay, pw-play, aplay or canberra-gtk-play

Linux has no single player, so use the one your desktop has. The freedesktop sound theme in /usr/share/sounds/freedesktop/stereo/ gives you ready-made files such as complete.oga, message-new-instant.oga, bell.oga and dialog-warning.oga:

The theme files come from the sound-theme-freedesktop package on Debian and Ubuntu. Run ls /usr/share/sounds/freedesktop/stereo/ to see what you have, and try a command in a terminal before you put it in settings.json.

Don't block Claude: run the sound in the background

By default, a hook blocks Claude until it finishes. A sound has nothing to report back, so add "async": true to a command hook and Claude carries on while the sound plays:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff",
            "async": true
          }
        ]
      }
    ]
  }
}

• async works on "type": "command" hooks only. An async hook can't block or steer Claude, which is fine for a sound.
• Once an async hook is running in the background, Claude Code doesn't enforce its timeout.
• Without async, set a timeout in seconds so a stuck audio device can't hold Claude up: the default for a command hook is 600 seconds. "timeout": 5 is plenty for a chime.
• Because a hook blocks until it finishes, a PermissionRequest sound without async can delay the prompt, so make that one async.

No sound? Troubleshooting

Work down this list from the top.

• Your terminal gets no desktop notification. The default "preferredNotifChannel": "auto" sends one in iTerm2, Ghostty and Kitty, rings the bell in Terminal.app only when its audible bell is off, and does nothing elsewhere, so set terminal_bell or use a hook.
• Apple Terminal's audible bell is off. If you accepted Claude Code's first-run terminal setup, it turned that off in your profile. With the default auto, Claude Code then rings the bell in Terminal.app only because the audible bell is off, and you hear nothing. For a sound, set "preferredNotifChannel": "terminal_bell" and turn the bell back on under Settings > Profiles > Advanced > "Audible bell", or use a hook.
• The VS Code terminal bell is silent. VS Code plays the bell sound only if accessibility.signals.terminalBell allows it, and its default (auto) means only when a screen reader is attached. Set "accessibility.signals.terminalBell": { "sound": "on" } in VS Code's settings, or use a hook, which doesn't depend on the terminal.
• Volume and output. A hook's player uses your current output device and volume, so check both, and that nothing is muted.
• The hook never ran. In an interactive session, Claude Code holds back hooks from every settings file, including your own ~/.claude/settings.json, until you accept the workspace trust dialog for the folder. Then type /hooks and check the hook is listed under the right event; the menu is read-only. Run the command in your own shell first. For details, start Claude Code with claude --debug-file claude-debug.log (any path works) and read the file. Plain claude --debug writes to ~/.claude/debug/<session-id>.txt and prints nothing to the terminal.
• It isn't time yet. permission_prompt waits about six seconds and idle_prompt about 60. The built-in alert is aimed at moments when you appear to be away from the terminal, so it may stay quiet while you are typing in the window. Stop fires after every response, but not after an interrupt.
• A player is missing. command not found for paplay or aplay means the package from the Linux table isn't installed. aplay can't play .oga or .mp3.
• Windows paths in JSON. settings.json is JSON, so every backslash is written twice: C:\\Windows\\Media\\chimes.wav. A single backslash is a broken escape.
• You are on SSH. The terminal bell reaches your local terminal, but a hook plays on the remote machine, which may have no speakers.
• tmux. The built-in desktop notification needs set -g allow-passthrough on in ~/.tmux.conf to reach the outer terminal.

Turn the sound off

Which switch you need depends on where the sound comes from:

With anotifier, from the least to the most permanent:

• npx anotifier@latest snooze 2h silences every channel for a while, the toast and its sound and the terminal bell included. snooze off cancels it, and snooze alone shows the current state.
• Quiet hours silence every channel inside a daily window. They are off by default: set quietHours.enabled to true, and from and to as "HH:MM", such as 22:00 to 08:00.
• The toast and its sound: toast.enabled: false in ~/.anotifier/config.json for every event, or toastEnabled: false under one event in events. The terminal bell is a separate switch (terminalBell.enabled: false, or terminalBellEnabled: false for one event, as in Sounds with anotifier), and turning it off leaves the toast's sound on.
• npx anotifier@latest uninstall asks (y/N) first, backs up the files it edits to ~/.anotifier/backups/, and removes anotifier's hooks from the tools it wired. It keeps ~/.anotifier/, and it doesn't touch Claude Code's preferredNotifChannel or hooks you wrote yourself, so a sound from either keeps playing.

Sounds with anotifier

npx anotifier@latest setup

anotifier plays a sound with each desktop toast and rings the terminal bell, with different defaults for finished and needs-you events. Set the sound per event with toastSound in ~/.anotifier/config.json. This example uses macOS names:

• Windows takes the notification sound names Default, IM, Mail, Reminder, SMS, and Alarm.
• macOS maps those names to built-in sounds (Mail to Purr, SMS to Tink, Alarm to Sosumi), and also accepts any of the 14 built-in names directly.
• Linux ignores sound names; urgent events are sent at critical urgency instead.
• anotifier config sounds changes them interactively.

{
  "events": {
    "task_complete": {
      "toastSound": "Hero"
    },
    "needs_input": {
      "toastSound": "Sosumi"
    }
  }
}

The terminal bell is on by default, and it is separate from the toast's sound. With Claude Code 2.1.141 and newer, it rings through Claude Code's own terminal output, which also works inside tmux and GNU screen. Turn it off for one event with terminalBellEnabled, or for all of them with terminalBell.enabled:

{ "events": { "task_complete": { "terminalBellEnabled": false } } }

Try it

One command wires every agent you have installed: Claude Code, Codex CLI, Cursor, and Gemini CLI.

npx anotifier@latest setup

Other guides

Claude CodeCodex CLICursorGemini CLIClaude Code permissionsClaude Code usage limitsClaude Code auto-compactClaude Code hooks securityccnotifyCodex CLI soundsAntigravity CLIWindows & WSLmacOS & LinuxAgent hooksTroubleshootingntfy phone pushWSL Windows toast