Claude Code Hooks: Audio Feedback For Claude Code

Integrating Sound Notifications for Claude Code

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 - a simple way to get sound notifications when Claude needs your attention or finishes a task.

The Problem I Was Trying to Solve

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:

• You're working on something else while Claude processes a big task
• Claude needs your input but you don't notice
• You're debugging and going back and forth with Claude
• You have multiple windows open and lose track

What I Built

My solution is pretty simple: hooks that play sounds when certain things happen in Claude Code. Here's what it does:

• Plays one sound when Claude needs your attention
• Plays a different sound when Claude finishes a task
• Also works when Claude's subagents (smaller helper processes) finish their work
• Logs everything to files so you can see what happened later

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.

How It Works

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:

• Mac: afplay (comes with macOS)
• Windows: PowerShell's SoundPlayer (built-in)
• Linux: aplay or paplay (usually already there)

Setting It Up

Getting this working is pretty easy. I even made an install script to make it simpler:

Quick setup with the install script:

1. Get the code: Clone my GitHub repo
2. Run the installer: Just run ./install-global.sh from the repo
3. That's it: The script sets everything up for you

Manual setup (if you want to do it yourself):

1. Get the code: Clone my GitHub repo
2. Add sound files: Put two .wav files in the folder - one for "needs attention" and one for "task complete"
3. Configure Claude: The .claude/settings.json file tells Claude Code which hooks to use
4. Test it: Run the hooks manually to make sure they work

The 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.

Why I Built This

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:

• TypeScript instead of JavaScript - Better for catching errors and easier to maintain for the AI itself
• Native audio instead of npm packages - Keeps it simple and avoids dependency issues
• Direct TypeScript execution - No build step needed, just run with npx tsx
• JSON logging - Simple but useful for tracking what happened

What I Learned

After using this for a two days, I noticed some cool benefits:

• Better flow - I don't have to keep checking if Claude is done. The sound tells me.
• Smoother workflow - I can work on other things while Claude processes big tasks.
• Better understanding - The logs help me see patterns in how Claude works.

What's Next

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.

Try It Yourself

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:

• Testing on different operating systems
• Adding new types of hooks
• Making the setup process even easier
• Building integrations with other development tools

Final Thoughts

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.