Claude Code's built-in notifications: the terminal bell and preferredNotifChannel

01The quick fix

If you hear nothing when Claude finishes, add this to ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Then make sure your terminal does something with the bell: plays a sound, bounces the Dock icon, flashes the tab or raises a notification. That setting lives in the terminal, not in Claude Code. On Mac, Windows and Linux most terminals have a "bell" or "alert" section in their preferences.

02Every preferredNotifChannel value

The setting can go in any settings file: user (~/.claude/settings.json), project (.claude/settings.json) or local (.claude/settings.local.json). Older versions kept it in ~/.claude.json, and Claude Code still reads a value left there.

03When the built-in notification fires

According to Anthropic's documentation, the built-in alert shares its timing with the Notification hook. In a terminal session:

• Permission prompt: after the prompt has waited about six seconds without a keystroke. Each key you press restarts the wait.
• Finished: about 60 seconds after Claude stops, and only if you have not typed since and no background agent is still running.

So the built-in "finished" alert is deliberately not instant. It is designed to reach you when you have wandered off, not to ping you while you watch. If you want an alert the moment a turn ends, use a Stop hook instead (see the Stop hook guide).

04Terminal by terminal

iTerm2 (macOS)

iTerm2 gets a desktop notification by default, but iTerm2 only shows it after you allow it:

1. Open Settings > Profiles > Terminal.
2. Check Notification Center Alerts.
3. Click Filter Alerts and enable Send escape sequence-generated alerts.

Also check that iTerm2 is allowed to show notifications in System Settings > Notifications.

Apple Terminal (macOS)

Apple Terminal gets no desktop notification. With "auto", Claude Code sends a silent bell only when it finds Audible bell turned off in the front window's profile. The bell then shows as a window flash, or a Dock bounce while Terminal is in the background, if the profile's Visual bell or Dock bounce option is on.

Watch for one detail. If you accepted Claude Code's first-run terminal setup prompt, it ran /terminal-setup, which turns the audible bell off in your Apple Terminal profile. To hear a sound, set "terminal_bell" and turn Audible bell back on under Settings > Profiles > Advanced.

Ghostty and Kitty (macOS and Linux)

Both get a desktop notification with no setup, and both forward it to your operating system's notification center.

Everything else

Windows Terminal, GNOME Terminal, Konsole, Alacritty, WezTerm, Warp and IDE terminals get nothing by default. Set "terminal_bell" and turn on the terminal's own bell handling, or use a hook. IDE terminals have their own quirks, covered in the VS Code, Cursor and JetBrains guide.

05Over SSH and inside tmux

The desktop notification is an escape sequence that the terminal on your own computer interprets, so it reaches you even when Claude Code runs on a remote server over SSH. Ghostty and Kitty forward it with no extra setup. iTerm2 needs the alert settings above.

Inside tmux, the sequence is swallowed unless you allow passthrough. Add this to ~/.tmux.conf and run tmux source-file ~/.tmux.conf:

set -g allow-passthrough on

Detached sessions are a different problem: if no terminal is attached, nothing can show the alert. See the tmux guide and notifications over SSH.

06The built-in alert and hooks together

Notification hooks run alongside the built-in alert; they do not replace it. Anthropic's documentation is explicit that hooks fire even with "notifications_disabled": the setting only changes how Claude Code alerts you, not whether your hook runs. That gives you a clean split:

• Keep "auto" or "terminal_bell" for the alert at the desk.
• Add a hook for anything else, such as a system sound, a desktop notification in a terminal that gets none, or a push to your phone with ntfy.
• If a hook already shows a desktop notification, set "notifications_disabled" to avoid seeing two.

For example, this plays a sound on macOS whenever Claude needs attention, in any terminal:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Linux and Windows equivalents are in the Linux guide and the Windows guide.

07Limits of the built-in options

• It stays on the computer. The bell or notification comes from the terminal on your screen. Walk to the kitchen and you miss it.
• It depends on the terminal. Many popular terminals get nothing until you change a setting.
• You cannot answer it. It tells you Claude is waiting; you still have to come back to the keyboard.

Anthropic's Remote Control, with the Claude mobile app, is the official way to get phone pushes. The comparison guide covers it next to the other options.

08Where Claude Code Notifier fits

If you work at your desk, the built-in alert plus "terminal_bell" may be all you need. Claude Code Notifier is for when you are not at the desk. Its command line tool, ccn, runs as a Claude Code hook, so it works in any terminal on Mac, Windows and Linux, with or without bell settings. On its own it shows a desktop notification when Claude finishes, needs a permission or asks a question. With a phone paired, you can allow or deny permissions, answer Claude's questions and send the next instruction from the phone, and if you typed in the last 30 seconds nothing waits on the phone at all. See the ccn page.

09FAQ