preferredNotifChannel: Claude Code's Built-In Notification Setting

Somewhere in Claude Code's settings there is a single line that decides whether you ever find out that Claude finished — or sat waiting for your input for twenty minutes while you read Slack. That line is preferredNotifChannel, and most people have never set it. This guide explains what it does, every value it accepts, why the default silently does nothing in most terminals, and what to do when the built-in channels aren't enough.

What preferredNotifChannel actually controls

Claude Code fires a notification event in two situations: when it finishes a task, and when it pauses because it needs your permission or input. preferredNotifChannel chooses how that event reaches you. It lives as a top-level key in ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

That's the entire setup — no plugins, no hooks, no scripts. The interesting part is choosing the right value.

Every accepted value, explained

The setting accepts seven values: auto, iterm2, terminal_bell, iterm2_with_bell, kitty, ghostty and notifications_disabled.

auto (the default)

In iTerm2, Kitty, or Ghostty, auto sends a desktop notification through the terminal's own notification support. In every other terminal — including macOS Terminal.app, VS Code's integrated terminal, and most Linux setups — it does nothing at all. This is the number one reason people search "how to turn on Claude notifications": the default only works in three terminals, and silence looks the same as "notifications off."

terminal_bell

Rings the classic terminal bell instead of posting a desktop notification. This is the most portable choice — nearly every terminal can beep, including over SSH — but you have to make sure your terminal has an audible bell enabled, since many ship with it muted. Simple, reliable, and easy to miss if your volume is down.

iterm2 and iterm2_with_bell

iterm2 posts a macOS desktop notification via iTerm2's notification integration. For it to appear, iTerm2 must be allowed to notify in macOS System Settings, and you may need to enable the relevant alert in iTerm2's Profiles → Terminal settings. iterm2_with_bell does both at once — banner plus bell — which is the safest bet on iTerm2 because one of the two will always get through.

kitty and ghostty

The same idea for Kitty and Ghostty users: desktop notifications delivered through each terminal's native notification protocol. A nice property of these terminal-level channels is that they work over SSH — the escape sequence travels back through your session, so a remote Claude Code run can still pop a banner on your local machine.

notifications_disabled

Turns the channel off entirely. Useful on shared machines, in recorded demos, or in CI-like environments where a bell would be noise.

Which value should you pick?

• iTerm2 user: iterm2_with_bell — redundancy wins.
• Kitty or Ghostty user: stay on auto (it already works) or set the explicit value to be safe.
• macOS Terminal.app, VS Code, or anything else: terminal_bell — it's the only built-in channel that will do anything there.
• Working over SSH: terminal_bell, or your terminal's channel if it's iTerm2/Kitty/Ghostty — both survive the round trip.

When the built-in channels aren't enough

preferredNotifChannel is deliberately minimal. It can't run a custom script, can't send anything to your phone, can't distinguish "task finished" from "Claude is waiting for your input," and a bell is easy to miss with headphones off. If you've set it correctly and still keep coming back to a terminal that's been idle for half an hour, you've found its ceiling.

The next step up is Claude Code's hooks system, which can run any command on the Notification and Stop events — we walk through that in our hooks guide and the broader Claude Code notifications guide. And if the notification you keep seeing is macOS telling you "notifications are turned off for Claude", that's a different, system-level fix — covered in this dedicated post.

The two-minute setup, start to finish

1. Open ~/.claude/settings.json (create it if it doesn't exist).
2. Add "preferredNotifChannel": "iterm2_with_bell" (or the value that matches your terminal from the list above).
3. If you picked a desktop-notification channel, allow your terminal to send notifications in your OS settings.
4. Start a task that takes a minute, switch to another app, and confirm the alert arrives.

One line of JSON, one permission toggle, and Claude Code stops being the app you babysit and starts being the one that taps you on the shoulder when it actually needs you.