Developer guide · macOS

How to make Claude Code play a sound when it's done

To make Claude Code play a sound when it's done, add a Stop hook to ~/.claude/settings.json that runs afplay /System/Library/Sounds/Glass.aiff. For a sound when it needs your input or permission, add a Notification hook with the matcher permission_prompt and a different sound. Both use built-in macOS tools, so there's nothing to install.

Last updated: October 2026 · About 2 minutes · Claude Code on macOS

TL;DR

Paste this into ~/.claude/settings.json. You'll hear Glass when Claude finishes and Funk when it's waiting on you.

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

Already have a settings.json? Merge the "hooks" key into it instead of replacing the file.

Play a sound when Claude Code finishes (Stop hook)

Step by step

  1. Open ~/.claude/settings.json in any editor. If it doesn't exist, create it. This is your user-level file, so the sound works in every project.
  2. Add the Stop block from the snippet above. If the file already has a "hooks" key, put Stop inside it next to whatever's there.
  3. Save. Claude Code watches its settings files and usually picks up hook changes on its own. If nothing happens, start a new session.
  4. Type /hooks inside Claude Code. It opens a read-only list of your hooks, and you should see the Stop entry labeled as coming from user settings.

Now give Claude a small task, switch to another window, and wait for the chime.

Why it works

Claude Code fires a Stop event every time it finishes responding, and a hook is a shell command attached to that event. afplay is the audio player that ships with macOS. Together, they give you a sound at the end of every turn.

Stop doesn't take a matcher. It fires on every finished turn, and that's what you want here.

The "async": true line tells Claude Code to run the command in the background so it doesn't wait for the sound to finish playing.

Play a sound when Claude Code needs your input or permission (Notification hook)

The finish sound covers half of it. The other half is when Claude stops halfway through a task to ask "can I run this command?" and sits there until you come back. That's the Notification event.

"Notification": [
  {
    "matcher": "permission_prompt",
    "hooks": [
      { "type": "command", "command": "afplay /System/Library/Sounds/Funk.aiff", "async": true }
    ]
  }
]

permission_prompt vs idle_prompt: which matcher to use

Notification fires for several kinds of notifications, and the matcher picks which ones play a sound. The two that matter here:

The TL;DR uses permission_prompt|idle_prompt to cover both. If the idle nudge gets annoying, drop it and keep "matcher": "permission_prompt". If you want a sound for every notification type, delete the matcher line entirely.

These names come from the official Claude Code hooks reference, which also lists newer types like agent_needs_input. Anthropic adds and renames these from time to time, so check that page if a matcher stops firing.

You no longer need jq to filter for permission prompts. Older guides (including an earlier version of this one) read the event JSON and checked notification_type by hand. The matcher does that for you now.

Use a different sound for "done" and "needs you"

Give each event its own sound. Within a day or two you'll know from across the room whether Claude finished or got stuck. Glass for done and Funk for needs-you works well because one is bright and the other is low. Hero and Submarine are another good pair.

Pick a sound: macOS system sounds

Every Mac has these in /System/Library/Sounds/:

Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

To see the exact list on your machine:

ls /System/Library/Sounds/

To hear one before you commit to it:

afplay /System/Library/Sounds/Glass.aiff

Swap the filename in your hook to change the sound. The path is case-sensitive in some setups, so copy it exactly as ls shows it.

Use your own .mp3, .wav or .m4a

afplay plays most audio formats. Point it at any file:

{ "type": "command", "command": "afplay ~/Sounds/claude-done.mp3", "async": true }

Keep the clip short. A 10-second song plays to the end on every turn.

Add a desktop banner too

A sound is easy to miss with headphones off. You can add a macOS notification banner by putting a second handler in the same group:

"Notification": [
  {
    "matcher": "permission_prompt",
    "hooks": [
      { "type": "command", "command": "afplay /System/Library/Sounds/Funk.aiff", "async": true },
      { "type": "command", "command": "osascript -e 'display notification \"Needs you\" with title \"Claude Code\"'", "async": true }
    ]
  }
]

The first time it runs, macOS may ask whether your terminal app can send notifications. Allow it, or the banner won't show.

Troubleshooting

Rather not touch the JSON? MacYaps writes these hooks for you with one toggle. If you're sticking with the manual setup, here's what usually goes wrong.

No sound at all. Run the command yourself in a terminal:

afplay /System/Library/Sounds/Glass.aiff

If that's silent too, it's your volume or output device, not Claude Code.

The command works but the hook never fires. Type /hooks in Claude Code. If your hook isn't listed, the settings file didn't load. Check that it's at ~/.claude/settings.json (not settings.json.txt, which TextEdit likes to do) and start a new session.

The file has a JSON error. It almost always happens when you merge into an existing file. Look for a missing comma between "hooks" and the key before it, or a trailing comma after the last item. To check the file:

python3 -m json.tool ~/.claude/settings.json

It prints the file back if it's valid and points at the line if it isn't.

error: unknown option '--global'. Some older guides tell you to add hooks with a claude config ... --global command. Current versions don't accept that flag for hooks. Edit settings.json directly instead.

Two sounds play at once. You probably have the same hook in both ~/.claude/settings.json and a project's .claude/settings.json with slightly different commands. /hooks shows where each one comes from.

Windows and Linux

The hook config is the same on every platform. Only the command changes.

Linux:

{ "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga", "async": true }

Use aplay with a .wav file if you don't have PulseAudio or PipeWire.

Windows (PowerShell):

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

MacYaps is a Mac app, so the one-click option below is macOS only.

Skip the JSON: MacYaps

The hooks above work fine. Living with them gets old: the same ding hundreds of times a day, hand-editing JSON on every Mac you use, and digging through the file again when you want to turn it off.

MacYaps writes the same hooks for you. Flip one toggle in the Agents tab and it adds them. Flip it off and it removes them cleanly. Instead of one system sound, you pick a character voice pack for "needs you" and another for "done", and they shuffle so you don't tune them out. There's an on/off switch in the menu bar for meetings.

$4.99 once, macOS 13 or later.

FAQ

How do I make Claude Code play a sound when it's done?

Add a Stop hook to ~/.claude/settings.json that runs afplay /System/Library/Sounds/Glass.aiff. Claude Code fires Stop every time it finishes responding, so the sound plays at the end of each task.

How do I get a sound when Claude Code needs my permission or input?

Add a Notification hook with "matcher": "permission_prompt" and point it at a different sound, like Funk.aiff. Add idle_prompt to the matcher if you also want a sound when Claude is waiting for your next message.

What's the difference between permission_prompt and idle_prompt?

permission_prompt fires when Claude needs you to approve an action, like running a command. idle_prompt fires when Claude is sitting at the prompt waiting for you to type. Most people want permission_prompt at minimum.

Where are the macOS system sounds like Glass.aiff?

In /System/Library/Sounds/. Run ls /System/Library/Sounds/ to list them and afplay /System/Library/Sounds/Glass.aiff to hear one.

Does a sound hook slow Claude Code down?

Not noticeably. Set "async": true on the hook and Claude Code runs it in the background instead of waiting for the sound to finish.

Does this work on Windows or Linux?

Yes. The hooks are identical. Swap afplay for paplay or aplay on Linux, or PowerShell's Media.SoundPlayer on Windows.

Do I need MacYaps for this?

No. Everything on this page works with what ships on your Mac. MacYaps just writes and removes the hooks for you and adds voice packs and a menu bar switch.

Related guides