Gabriel Márquez

Field note / Claude Code

Desktop Notifications for Claude Code

Never miss when Claude Code finishes a task — set up desktop notifications with sound alerts in under a minute.

3 min read

  • Claude Code
  • Productivity
  • Linux
  • macOS

If you use Claude Code for long-running tasks — refactors, test suites, complex debugging — you’ve probably switched to another window and missed when it finished. You come back minutes later to find it’s been waiting for your input the whole time.

There’s a simple fix: Claude Code supports hooks, shell commands that run in response to events. One of those events is Notification, which fires whenever Claude needs your attention. Wire it up to your OS notification system and you’ll never miss a prompt again.

The Setup

All you need to do is add a hook to your Claude Code settings file at ~/.claude/settings.json.

Linux (GNOME / KDE / most distros)

This uses notify-send for the desktop notification and paplay for an audio alert:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.message // \"Claude needs your attention\"' | { read -r msg; notify-send -u normal -i dialog-information 'Claude Code' \"$msg\"; paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null & }",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Dependencies (pre-installed on most Ubuntu/Fedora/GNOME setups):

  • libnotify-bin — provides notify-send
  • pulseaudio-utils — provides paplay

If you’re missing either:

# Debian / Ubuntu
sudo apt install libnotify-bin pulseaudio-utils

# Fedora
sudo dnf install libnotify pulseaudio-utils

macOS

On macOS, use osascript for notifications and afplay for sound:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.message // \"Claude needs your attention\"' | { read -r msg; osascript -e \"display notification \\\"$msg\\\" with title \\\"Claude Code\\\"\"; afplay /System/Library/Sounds/Glass.aiff & }",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

No extra dependencies needed — osascript, afplay, and jq are available out of the box (or via Homebrew for jq).

How It Works

Claude Code hooks let you attach shell commands to lifecycle events. The Notification event fires whenever Claude wants your attention — for example, when it finishes a task, hits an error, or needs approval for a tool call.

The hook receives a JSON payload on stdin with a .message field. The command:

  1. Extracts the message with jq, falling back to a default string
  2. Shows a desktop notification via notify-send (Linux) or osascript (macOS)
  3. Plays a sound so you hear it even if you’re not looking at the screen

Adding to Existing Settings

If you already have a ~/.claude/settings.json with other configuration, just merge the hooks key into your existing file. For example:

{
  "permissions": {
    "allow": ["Bash(git:*)"]
  },
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.message // \"Claude needs your attention\"' | { read -r msg; notify-send -u normal -i dialog-information 'Claude Code' \"$msg\"; paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null & }",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Customizing

You can swap the sound file for any .oga or .wav file on Linux, or any audio file on macOS:

# Use a different sound on Linux
paplay /usr/share/sounds/freedesktop/stereo/bell.oga

# Use a different sound on macOS
afplay /System/Library/Sounds/Ping.aiff

You can also change the notification urgency on Linux (low, normal, critical) or add an expiration timeout:

# Critical urgency, expires after 10 seconds
notify-send -u critical -t 10000 'Claude Code' "$msg"

Wrapping Up

This is a small quality-of-life improvement that adds up fast. Set it once, and you’ll always know when Claude Code is ready for you — no more tab-switching to check, no more wasted idle time.

← All writing