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.
| Terminal | What Claude Code does | To make it work |
|---|---|---|
| Ghostty, Kitty | A desktop notification | Nothing; allow the terminal’s notifications in System Settings |
| iTerm2 | A desktop notification, once alerts are on | Settings › Profiles › Terminal: turn on Notification Center Alerts, then Filter Alerts › Send escape sequence-generated alerts |
| Apple Terminal | A silent bell, only if the profile’s audible bell is off | Set preferredNotifChannel to terminal_bell and turn on Audible bell in Settings › Profiles › Advanced |
| Warp, VS Code, others | Nothing | A hook, below, or terminal_bell |
| tmux | Nothing reaches the outer terminal | set -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.
| Terminal | Bundle ID for -activate |
|---|---|
| Terminal | com.apple.Terminal |
| iTerm2 | com.googlecode.iterm2 |
| Ghostty | com.mitchellh.ghostty |
| VS Code | com.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
- Script Editor has no permission.
osascriptfails silently and macOS doesn’t ask. Runosascript -e 'display notification "test"'once, then turn on Allow Notifications for Script Editor in System Settings › Notifications. Same for terminal-notifier and your terminal. - A Focus is on. Do Not Disturb or another Focus hides banners; check Control Center.
- The hook isn’t loaded. Type
/hooksand look for it. In a new folder, hooks wait until you accept the trust dialog. - The script fails. Pipe a sample into it by hand:
echo '{"cwd":"/tmp","message":"test"}' | ~/.claude/hooks/mac-notify.sh. A missingjqor a missingchmod +xare the usual causes. - tmux swallows the sequence. Turn on
allow-passthrough, as in the table above.
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
- Get notified when Claude Code finishesThe Stop hook on macOS, Windows and Linux, then on your phone.
- Play a sound when Claude Code finishesThe built-in bell, terminal by terminal, or a Stop hook that plays a sound.
- The Claude Code Notification hookWhen it fires, what notification_type means, and why it waits six seconds.
- Claude Code notifications over SSH and in tmuxAlerts from a server or a detached session, back to you.
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.