Claude Code notifications on macOS, iTerm2, Ghostty

Updated

Quick answer

On macOS, Claude Code notifies you by itself in iTerm2, Ghostty and Kitty, and stays silent in most other terminals. For a notification in any terminal, add a Stop hook and a Notification hook that run osascript or terminal-notifier. For an alert that follows you away from the Mac, send it to your iPhone.

What works without a hook

Claude Code alerts you when it finishes or waits for a permission and you seem to be away from the terminal. What you get depends on the terminal:

Swipe the table sideways to see all columns.

TerminalWhat Claude Code doesTo make it work
Ghostty, KittyA desktop notificationNothing; allow the terminal’s notifications in System Settings
iTerm2A desktop notification, once alerts are onSettings › Profiles › Terminal: turn on Notification Center Alerts, then Filter Alerts › Send escape sequence-generated alerts
Apple TerminalA silent bell, only if the profile’s audible bell is offSet preferredNotifChannel to terminal_bell and turn on Audible bell in Settings › Profiles › Advanced
Warp, VS Code, othersNothingA hook, below, or terminal_bell
tmuxNothing reaches the outer terminalset -g allow-passthrough on in ~/.tmux.conf, and preferredNotifChannel set to iterm2, kitty or ghostty

preferredNotifChannel goes in ~/.claude/settings.json, or in /config under Local notifications. The built-in alert has two limits: it says nothing about what Claude did, and the end-of-task alert comes about a minute after Claude finishes. A hook fixes both.

A hook with osascript

osascript ships with macOS. One script serves both hooks: on Stop it shows Claude’s last message, on Notification the reason Claude is waiting.

~/.claude/settings.json

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/mac-notify.sh" }] }],
    "Notification": [
      {
        "matcher": "permission_prompt|elicitation_dialog",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/mac-notify.sh" }]
      }
    ]
  }
}

~/.claude/hooks/mac-notify.sh, then chmod +x (needs jq)

#!/bin/sh
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
msg=$(printf '%s' "$input" | jq -r '.last_assistant_message // .message // "Claude Code"' | head -c 180)
osascript -e 'on run argv' \
  -e 'display notification (item 2 of argv) with title (item 1 of argv) sound name "Glass"' \
  -e 'end run' "Claude Code · $project" "$msg"
exit 0

Passing the text as arguments, rather than inside the AppleScript, keeps quotes in Claude’s message from breaking the command. Any sound from /System/Library/Sounds works: Basso, Glass, Hero, Ping, Submarine and others. The Stop entry tells you when a turn is over; the Notification entry, when Claude waits for a permission or a form, about six seconds after it appears if you haven’t typed. Keep both: they cover different moments.

terminal-notifier: sound and click to focus

A notification from osascript belongs to Script Editor, and clicking it opens Script Editor. terminal-notifier, installed with brew install terminal-notifier, lets a click bring your terminal forward, and replaces the previous alert of the same project instead of stacking them:

Replace the osascript line

terminal-notifier -title "Claude Code" -subtitle "$project" -message "$msg" \
  -sound Glass -group "claude-$project" -activate com.googlecode.iterm2

Swipe the table sideways to see both columns.

TerminalBundle ID for -activate
Terminalcom.apple.Terminal
iTerm2com.googlecode.iterm2
Ghosttycom.mitchellh.ghostty
VS Codecom.microsoft.VSCode

In terminals that read notification escape sequences, such as Ghostty or Warp, a hook can also return {"terminalSequence": "..."} with an OSC 777 sequence, and Claude Code emits it for you; hooks can’t write to the terminal themselves.

If nothing shows

From the Mac to your iPhone

A notification on the Mac only helps while you are at the Mac. To get the same moments on your iPhone, a hook can post to a push service such as ntfy, one-way, or, with a Claude plan and Remote Control, the Claude app can push permission prompts and questions. Monish sends them with buttons: install the app, then run curl -fsSL https://monish.cc/install.sh | sh -s with the 6-digit code it shows. On a Mac signed in to the same Apple Account, tap Copy in the app and paste it in the terminal. You then allow, deny or reply from the lock screen, and while you’re typing in the terminal, your iPhone stays quiet.

Questions

Why does iTerm2 show nothing?
iTerm2 shows Claude Code’s notifications only once its alerts are on: Settings › Profiles › Terminal › Notification Center Alerts, then Filter Alerts › Send escape sequence-generated alerts.
Which sounds can the hook play?
Any file in /System/Library/Sounds, by name: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink.
Do I need jq?
The scripts here use jq to read the JSON Claude Code sends. Run jq --version; if it is missing, install it with Homebrew.
Does it work when Claude Code runs on a server over SSH?
A desktop hook would run on the server, which has no screen. Set preferredNotifChannel on the server to your local terminal’s value, iterm2, kitty or ghostty, so the notification travels back, or send it to your phone.

More guides

New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.

Get Monish on your iPhone

Free, no account. Your 6-digit code is waiting in the app.

Download on the App Store