Claude Code notifications: terminal bell, desktop alerts, hooks and phone pushes

Claude Code notifies you when it finishes a task or waits on a permission prompt while you are away. In iTerm2, Ghostty and Kitty you get a desktop notification out of the box; in any other terminal, set "preferredNotifChannel": "terminal_bell" or add a Notification hook. With Remote Control connected, Claude can also push alerts to your phone.

This guide walks through each option, when each notification type fires, and how to fix the usual reasons alerts never show up. Everything here comes from the official terminal configuration and hooks reference pages.

When does Claude Code send a notification?

Claude Code fires a notification event when Claude finishes a task or pauses for a permission prompt, and you appear to be away from the terminal. The "appear to be away" part matters: if you are typing in the session, you will not see most alerts.

The hooks reference gives the exact timing for the common types:

There are more types, including ones for usage limit auto-resume and mod notifications. Each keystroke defers the six-second timer for permission_prompt, and idle_prompt waits while a background subagent is still running. If you want something to happen the instant Claude asks for permission, use the PermissionRequest hook instead.

How do you turn on the terminal bell?

The preferredNotifChannel setting controls the built-in alert. It appears in /config as Local notifications, and you can set it in any settings file:

{
  "preferredNotifChannel": "terminal_bell"
}

The documented values are:

• auto (default): a desktop notification in iTerm2, Ghostty and Kitty; in Terminal.app it rings the bell only when Terminal's audible bell is off; elsewhere it does nothing
• terminal_bell: rings the bell character in any terminal
• iterm2 and iterm2_with_bell: an iTerm2 notification, optionally with the bell
• kitty and ghostty: that terminal's desktop notification
• notifications_disabled: no notification

On macOS, if you accepted the first-run terminal setup prompt, /terminal-setup turned off the audible bell in your Apple Terminal profile. You can turn it back on under Settings, Profiles, Advanced, "Audible bell". More terminal tweaks are in the terminal setup guide.

How do you get desktop notifications?

In Ghostty and Kitty, the default auto setting is enough. The notification also travels back over SSH, so a remote session can still alert your local machine.

iTerm2 needs one change to forward the alert to your OS notification center, including from SSH sessions. Go to Settings, Profiles, Terminal, check "Notification Center Alerts", then click "Filter Alerts" and enable "Send escape sequence-generated alerts".

Terminals that do not receive the built-in desktop notification, such as Warp or the VS Code integrated terminal, can use the terminal bell or a hook. If notifications still do not appear, check that your terminal app has notification permission in your OS settings.

How do you use a Notification hook?

A hook is a command Claude Code runs at a lifecycle event. The Notification event runs alongside the built-in notification rather than replacing it, so you can add a sound, a native desktop alert or a message to a chat tool. The hooks guide gives a native command per platform. This example is the macOS version, added to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

On Linux the docs use notify-send 'Claude Code' 'Claude Code needs your attention', and on Windows a PowerShell message box. For a sound on macOS, the terminal docs use afplay /System/Library/Sounds/Glass.aiff as the command.

Two platform notes from the docs. On macOS, osascript routes notifications through Script Editor, and if Script Editor lacks notification permission the command fails silently; run osascript -e 'display notification "test"' once, then allow Script Editor under System Settings, Notifications. On Linux, notify-send needs a notification daemon, which headless servers, SSH sessions and most containers lack, and on Debian and Ubuntu it comes from the libnotify-bin package.

To treat types differently, give each its own matcher, for example one script for permission_prompt and another for idle_prompt. The hook receives JSON on stdin with message, an optional title and notification_type, so one script can also branch on the type itself.

Hooks fire even when preferredNotifChannel is notifications_disabled. That setting changes how you are alerted, not whether your hook runs, so you can silence the built-in alert and rely entirely on your own script.

How do you get notifications inside tmux?

By default tmux swallows the escape sequence, so desktop notifications never reach the outer terminal. Add these lines to ~/.tmux.conf and run tmux source-file ~/.tmux.conf:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

The allow-passthrough line is the one that lets notifications through. The extended-keys lines fix Shift+Enter inside tmux at the same time.

Can Claude Code notify your phone?

Yes, through Remote Control. While a session is connected, Claude can push alerts to the Claude mobile app. The setup steps are:

1. Install the Claude app for iOS or Android.
2. Sign in with the same account and organization you use for Claude Code.
3. Accept the operating system's notification prompt.
4. Run /config in your terminal and enable Push when Claude decides, Push when actions required, or both.

"Push when Claude decides" (the agentPushNotifEnabled setting) lets Claude choose, usually when a long task finishes or it needs a decision. You can also ask in your prompt, such as "notify me when the tests finish". "Push when actions required" (inputNeededNotifEnabled) sends one when a permission prompt or question is waiting. Beyond those two toggles there is no per-event configuration.

Claude Code skips phone pushes while you are typing in or focused on the connected terminal. If pushes do not arrive and /config shows No mobile registered, open the Claude app so it refreshes its push token. On iOS, Focus modes and notification summaries can delay pushes; on Android, exempt the Claude app from battery optimization.

What about the desktop app?

The Claude desktop app sends an OS notification when a Code session finishes a task and you are not viewing that session; sessions that belong to a project send the project's notifications instead. Sessions you start from your phone with Dispatch send a push notification when they finish or need approval.

How do you troubleshoot missing notifications?

Work through this list in order:

1. Are you actually away? Most types wait for about six or 60 seconds without typing. Test by starting a task and switching windows.
2. Does your terminal support the built-in alert? If not, set terminal_bell or add a hook.
3. Does the terminal app have OS notification permission? Check System Settings or your desktop environment.
4. Are you in tmux? Enable passthrough as shown above.
5. Is the hook loading? Run /hooks to see configured hooks, and run the command by hand to confirm it works outside Claude Code.

Keep your notification setup with your other prompts

A good hook command or tmux snippet tends to get copied between machines. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, so the prompts you reuse alongside Claude Code stay in one place you control.