Blog · September 9, 2026 · 6 min read · by Vilva Athiban P B

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.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read