ArticleOctober 12, 2025Free to read

Add Sound Alerts to Claude Code with Hooks and macOS afplay

Use different sounds when Claude Code needs approval and when a task finishes, connecting hooks to local audio playback on macOS.

Original video in Chinese.

Key Takeaways

  • Sound alerts reduce the need to keep checking whether Claude Code is waiting for approval or has completed a task.
  • In my setup, Notification events for permission prompts and Stop events triggered local MP3 playback through macOS afplay.
  • Configure the project through its .claude folder or the /hooks interface. The same mechanism can also run scripts that connect to broader workflows.

This is a setting I strongly recommend adding to Claude Code.

The most frustrating part of the version I used was its lack of alerts. It would work quietly, finish without telling me, or wait for an Enter-key confirmation before continuing.

Watching constantly wastes time; checking only occasionally slows development. I wanted one sound when approval was needed and another when the task was ready for review.

In my demonstration, a permission prompt played music from The Legend of Zelda. Completion played Super Mario music. Both were MP3 files downloaded and stored locally.

Connect hooks to audio playback

The first part is Claude Code’s hooks feature. A hook runs an action when a specified event occurs.

For my two examples, a Notification asking for permission was one event and Stop, indicating the task had finished, was another.

The second part is macOS’s built-in command-line tool afplay, short for Audio File Play. Supply an audio file path after the command to play it from the terminal.

In my configuration, the Stop hook ran afplay with the Super Mario file. The permission-related Notification hook ran afplay with the Zelda file.

The project configuration was in the .claude folder under the project root. I shared the code in the newtype community.

If you prefer using the interface, enter /hooks and press Enter. Choose a hook such as Notification and enter the command you want it to run. I personally found editing the configuration file simplest.

Beyond sound effects

I had not seen much discussion of hooks in China, but the feature has considerable potential.

My commands were simple. More elaborate actions could run Python scripts, connecting Claude Code to other parts of a workflow. I planned to share those advanced uses in the community as I explored them.

That is all for this episode. If you want to understand AI, become a more capable independent creator, and meet people with similar interests, join the newtype community. See you next time.