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.
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.
~/.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.Stop block from the snippet above. If the file already has a "hooks" key, put Stop inside it next to whatever's there./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.
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.
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 }
]
}
]
Notification fires for several kinds of notifications, and the matcher picks which ones play a sound. The two that matter here:
permission_prompt fires when Claude needs you to approve something, like running a command or editing a file. If you only want a sound when you're the one blocking progress, use this one alone.idle_prompt fires when Claude has been sitting at the prompt waiting for your next message.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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
In /System/Library/Sounds/. Run ls /System/Library/Sounds/ to list them and afplay /System/Library/Sounds/Glass.aiff to hear one.
Not noticeably. Set "async": true on the hook and Claude Code runs it in the background instead of waiting for the sound to finish.
Yes. The hooks are identical. Swap afplay for paplay or aplay on Linux, or PowerShell's Media.SoundPlayer on Windows.
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.