Claude Code: Set up desktop notifications so you never miss an input request

If you use Claude Code on the command line, you probably know this situation: you start a task, switch to another window, or grab a coffee... and 10 minutes later you realize that Claude has been waiting for your input the whole time. That's annoying.

In this article, I like to show you how to set up desktop notifications on macOS and Linux so you instantly know when Claude Code needs your attention.

How does it work?

Claude Code has a hook system. Hooks are shell commands that run automatically at specific points in Claude Code's lifecycle.

For notifications, two hook events are relevant:

• Notification (with matcher idle_prompt): Fires when Claude is waiting for your input.
• Stop: Fires when Claude has finished its response.

macOS: terminal-notifier

terminal-notifier is a command-line tool that sends notifications directly to the macOS Notification Center. It gives you full control over title, message, and sound.

Installation

brew install terminal-notifier

Configuration

Open (or create) the file ~/.claude/settings.json and add this hook configuration:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message 'Waiting for your input' -sound Glass"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message 'Task completed' -sound Glass"
          }
        ]
      }
    ]
  }
}

A few notes on this:

The -sound Glass parameter plays a short sound. Other available sounds are: Basso, Blow, Bottle, Frog, Funk, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink.

If you only want this for a specific project, use .claude/settings.json in your project directory instead.

Allow notifications

Don't forget to check System Settings → Notifications and make sure terminal-notifier is allowed to send notifications. Otherwise nothing happens, and you'll wonder why.

Linux: notify-send

terminal-notifier is macOS only. On Linux, you can use notify-send instead, which uses the native desktop notifications of your environment (GNOME, KDE, etc.).

Installation

notify-send is pre-installed on many distributions. If not:

# Debian/Ubuntu
sudo apt-get install libnotify-bin

# Fedora/RHEL
sudo dnf install libnotify

# Arch Linux
sudo pacman -S libnotify

Configuration

The hook configuration in ~/.claude/settings.json looks almost the same; just the command changes:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Task completed'"
          }
        ]
      }
    ]
  }
}

You can verify that notify-send works before configuring the hooks:

notify-send "Test" "This is a test notification"

If a notification pops up, you're good to go.