Claude Code macOS system notifications

When multi-tasking with Claude, system notifications can help you know when it needs input or has completed its work. These steps are for macOS with Ghostty and tmux, but can be adapted to other setups.

1. Install terminal-notifier #

brew install terminal-notifier

2. Create the notification script #

Save this to a directory in your env path, in my case ~/.local/bin/claude-notify:

#!/bin/bash

# Capture tmux context for the pane where Claude is running (not the current view)
SESSION=$(tmux display-message -t "$TMUX_PANE" -p '#{session_name}')
WINDOW=$(tmux display-message -t "$TMUX_PANE" -p '#{window_index}')
WINDOW_NAME=$(tmux display-message -t "$TMUX_PANE" -p '#{window_name}')
SOCKET=$(echo "$TMUX" | cut -d',' -f1)
CLIENT=$(tmux display-message -p '#{client_tty}')

terminal-notifier \
  -title "Claude Code" \
  -subtitle "$SESSION:$WINDOW_NAME" \
  -message "${1:-Waiting for input}" \
  -sound default \
  -activate com.mitchellh.ghostty \
  -execute "/opt/homebrew/bin/tmux -S $SOCKET switch-client -c '$CLIENT' -t '$SESSION:$WINDOW'"

3. Configure Claude's hooks #

Add this to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/claude-notify"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/claude-notify"
          }
        ]
      }
    ]
  }
}

4. Configure MacOS notification system settings for the terminal-notifier app #

At this point claude should be sending notifications. Search for "Notifications" in settings, identify the terminal-notifier app, and adjust accordingly for the level of visibility that you want.