Never Miss a Beat: Sound & Visual Notifications for Claude Code

I run Claude Code across multiple terminal instances simultaneously. At any given moment I might have five or six instances working — one in my CFO repo, one in polaris, one doing research, another processing data. The problem is obvious: I'm context-switching between browser tabs, Slack, documents, and when Claude finishes a task or needs my approval, I have no idea unless I'm staring at that specific terminal.

Today I solved this properly, and it took about ten minutes. Here's exactly how to set it up so you can do the same. This works in any macOS terminal — Ghostty, iTerm2, Terminal.app, Kitty, Warp, Alacritty, whatever you use.

The Problem

Claude Code runs in your terminal. Terminals don't have push notifications. When Claude finishes a complex task and prints "ready for your input," you might not see it for five minutes because you're reading a doc in another window. When Claude needs permission to run a destructive command, it's blocked waiting on you while you're answering email.

Multiply this by several concurrent instances and you're leaving serious velocity on the table.

The Solution: Three-Tier Notification Hooks

Claude Code has a hooks system that fires shell commands on specific events. The Notification hook fires when Claude needs your attention. We're going to wire it up with:

1. Distinct sounds for different event types so you know what happened without looking
2. macOS notification banners so you can see which instance needs you
3. Click-to-focus so tapping the notification brings your terminal to the foreground

Step 1: Pick Your Sounds

macOS ships with 14 system sounds. Here's a quick script to audition them all:

#!/bin/bash
sounds=(Basso Blow Bottle Frog Funk Glass Hero Morse Ping Pop Purr Sosumi Submarine Tink)

echo "=== macOS System Sound Demo ==="
echo "Playing ${#sounds[@]} sounds with 2-second gaps"
echo ""

for i in "${!sounds[@]}"; do
  num=$((i + 1))
  echo "  [$num/${#sounds[@]}] ${sounds[$i]}"
  afplay "/System/Library/Sounds/${sounds[$i]}.aiff"
  sleep 2
done

Save that as play-sounds.sh, run it, and pick three sounds for three scenarios:

Step 2: Install terminal-notifier

The built-in osascript notifications work fine for sound + banner, but they don't support click-to-focus. terminal-notifier does — when you click the notification, it activates your terminal app.

brew install terminal-notifier

Step 3: Find Your Terminal's Bundle ID

The -activate flag needs your terminal's bundle identifier. Here are the common ones:

If your terminal isn't listed, you can find its bundle ID with:

osascript -e 'id of app "YourTerminalName"'

Step 4: Wire Up the Hooks

Edit your global Claude Code settings at ~/.claude/settings.json. Replace com.mitchellh.ghostty with your terminal's bundle ID from the table above:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission",
        "hooks": [{
          "type": "command",
          "command": "terminal-notifier -title 'Claude Code' -subtitle \"Permission Request [$(basename $PWD)]\" -message 'Approval needed — check your terminal' -sound Funk -activate com.mitchellh.ghostty"
        }]
      },
      {
        "matcher": "compact",
        "hooks": [{
          "type": "command",
          "command": "terminal-notifier -title 'Claude Code' -subtitle \"Compaction [$(basename $PWD)]\" -message 'Compacting context window — no action needed' -sound Sosumi -activate com.mitchellh.ghostty"
        }]
      },
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "terminal-notifier -title 'Claude Code' -subtitle \"Done [$(basename $PWD)]\" -message 'Task complete — ready for your input' -sound Hero -activate com.mitchellh.ghostty"
        }]
      }
    ]
  }
}

Let's break down what's happening:

The matcher field filters which notifications trigger each hook. "permission" catches permission prompts, "compact" catches compaction events, and "" (empty string) is the catch-all for everything else — which in practice means "task complete."

The $(basename $PWD) trick injects the current working directory name into the notification subtitle. When you're running five instances, seeing "Done [cfo]" vs "Permission Request [polaris]" tells you exactly which instance needs you without switching windows.

The -activate flag is the magic — clicking the notification brings your terminal to the foreground. This is the only part that's terminal-specific, and it's just a one-word swap of the bundle ID.

Step 5: Make Notifications Stick

By default, macOS notification banners disappear after a few seconds. If you want them to persist until you dismiss them:

System Settings → Notifications → terminal-notifier → change "Banners" to "Alerts"

Alerts stay on screen until you click Close or Action. This is the right choice when you're deep in another task and don't want to miss the notification.

Step 6: Test It

Run this from any terminal to verify (swap in your bundle ID):

terminal-notifier -title 'Claude Code' \
  -subtitle "Done [$(basename $PWD)]" \
  -message 'Task complete — ready for your input' \
  -sound Hero \
  -activate com.mitchellh.ghostty

You should see a notification banner with your directory name, hear the Hero sound, and clicking it should bring your terminal to front.

The Result

After this setup, my workflow looks like this:

1. I kick off work in multiple Claude Code instances
2. I go do something else — read, write, think, make coffee
3. I hear Funk and know Claude needs approval somewhere
4. I see "Permission Request [polaris]" and know exactly where
5. I click the notification and my terminal comes to front
6. I approve, Claude continues, I go back to what I was doing

The subtle but important detail: three distinct sounds means you can triage by ear. Sosumi (compaction) means "ignore, Claude is handling it." Hero (done) means "whenever you're ready." Funk (permission) means "Claude is blocked on you — go now."

Why This Matters More Than It Seems

I run Claude Code as my primary development interface. On any given day I might have instances working across a CFO financial repo, the main product codebase, a research project, and a one-off script. The limiting factor is no longer Claude's speed — it's my attention allocation across instances.

Before notifications, I was manually cycling through terminals to check status. That's maybe 30 seconds each time, multiplied by dozens of check-ins per day, across multiple instances. Call it 15-20 minutes of pure waste daily, plus the cognitive cost of interrupted flow.

After notifications, Claude tells me exactly when and where it needs me. I stay in flow on whatever I'm doing until I hear the sound. Simple tools, compounding returns.

Customization Ideas

A few things you could extend from here:

• Different sounds per directory — if you have a production repo that's higher stakes, give it a more urgent sound
• Slack webhook integration — pipe notifications to a Slack channel for team visibility
• Time-based filtering — quieter sounds during focus hours, louder during meetings when you might miss visual notifications
• Custom scripts — the hook command can be any shell script, so you could log notifications, aggregate stats, or trigger other automations

The hooks system is simple — it's just "run this shell command when this event fires." That simplicity is the feature. Stay light on tooling, heavy on context.

Quick Reference

Ten minutes of setup, permanent quality-of-life improvement. Ship it.