6 min read
Claude Code Hooks: Audio Feedback For Claude Code
TL;DR I've implemented audio notifcations for when Claude Code needs your attention. Publically available on GitHub, link down below.
Loading...
TL;DR I've implemented audio notifcations for when Claude Code needs your attention. Publically available on GitHub, link down below.
Have you tried Claude Code yet and wondered if it's done yet? You're coding away, switch to another window, and when you come back you realize Claude finished 10 minutes ago. Yeah, me too.
I got tired of constantly checking if Claude was ready for my next input. Coming from Cursor (which has nice audio feedback), I really missed those little sound cues. So I built something to fix this: Awesome Claude Code repository - a simple way to get sound notifications when Claude needs your attention or finishes a task.
Working with AI coding tools is great, but there's one annoying thing: you never know when they're done. Claude might be thinking, or it might be waiting for you. Without looking at the screen, you can't tell.
This gets really annoying when:
My solution is pretty simple: hooks that play sounds when certain things happen in Claude Code. Here's what it does:
The best part? It works on Mac, Windows, and Linux without installing anything extra. It uses the audio players that are already on your computer.
Claude Code has something called "hooks" - basically scripts that run when certain events happen. I wrote three TypeScript hooks that listen for different events:
Notification Hook - Runs when Claude needs you to do something Stop Hook - Runs when Claude finishes a task
Subagent Stop Hook - Runs when a subagent finishes
Each hook does two things: plays a sound and saves info about what happened to a log file.
Here's the basic idea in code:
import { execSync } from "child_process";
import { existsSync } from "fs";
// Check if sound file exists, then play it
if (existsSync("on-agent-complete.wav")) {
// Use the right command for each operating system
if (process.platform === "darwin") {
execSync("afplay on-agent-complete.wav");
} else if (process.platform === "win32") {
execSync(
"powershell -c \"(New-Object Media.SoundPlayer 'on-agent-complete.wav').PlaySync();\"",
);
} else {
execSync("aplay on-agent-complete.wav");
}
}
The hooks use commands that are already installed on most computers:
afplay (comes with macOS)aplay or paplay (usually already there)Getting this working is pretty easy. I even made an install script to make it simpler:
Quick setup with the install script:
./install-global.sh from the repoManual setup (if you want to do it yourself):
.claude/settings.json file tells Claude Code which hooks to useThe configuration file looks like this:
{
"hooks": {
"Notification": {
"command": "npx tsx .claude/hooks/notification.ts --notify"
},
"Stop": {
"command": "npx tsx .claude/hooks/stop.ts"
},
"SubagentStop": {
"command": "npx tsx .claude/hooks/subagent_stop.ts"
}
}
}
That's it. Once you have this set up, Claude Code will automatically run the hooks and play sounds when stuff happens.
I was inspired by Cursor's audio feedback feature. When I started using Claude Code more, I really missed having those audio cues. But instead of just complaining about it, I thought: "Claude Code has hooks, so I can probably build this myself."
The funny thing is, I built most of this while working with Claude itself. It felt a bit weird asking an AI to help me build better tools for working with AI, but it worked out great.
I made some specific choices while building this:
npx tsxAfter using this for a two days, I noticed some cool benefits:
I have some ideas for making this even better:
Git integration - Automatically create git commits when Claude finishes big tasks, so you can easily go back if something breaks.
Worktree management - Use git worktrees to keep subagent work separate from main development.
Better customization - Let people choose their own sounds and configure when notifications happen.
If you want to try this out, check out the Awesome Claude Code repository on GitHub. The README has step-by-step setup instructions.
You can also contribute if you have ideas for improvements. I'm particularly interested in:
This project started because I was annoyed by a small thing - not knowing when Claude was done with a task. But it turned into something that actually makes my daily coding better.
Sometimes the best improvements are the simple ones. Adding sound notifications doesn't change what Claude Code can do, but it makes it much nicer to use. And that matters when you're spending hours coding with AI assistance.
The real lesson here is that Claude Code's hook system is pretty powerful. This sound notification thing is just one example. There are probably lots of other ways to use hooks to make the development experience better.
What would you build with Claude Code hooks? I'd love to hear your ideas.
If you try this out or build something similar, let me know how it goes. The more we experiment with these tools, the better we can make them for everyone.