Claude Code Notifications on Mac: 4 Ways (2026)

Short answer: Claude Code already notifies you in Ghostty, Kitty and iTerm2 when it finishes or needs permission while you’re away from the terminal. Elsewhere, turn on the terminal bell or add a Notification hook. For your phone, use Remote Control’s push notifications. To approve, deny or answer without switching windows, use a notch app.

TL;DR

• Terminal: Ghostty and Kitty need no setup, iTerm2 needs two settings, and other terminals can ring the bell.
• Hook: a Notification hook shows a banner or plays a sound in any terminal; a Stop hook fires as each turn ends.
• Phone: Remote Control pushes prompts and questions to the Claude app on Claude Pro, Max, Team and Enterprise plans.
• Notch: a notch app turns the same events into cards you can approve, deny or answer.
• Codex has its own notify and tui.notifications settings.

Checked 7 October 2026 against Claude Code’s terminal, hooks and Remote Control docs. Disclosure: FavTray is our app; it’s one of the notch options in way 4.

Which Claude Code events can notify you?

Claude Code raises a Notification event when it needs permission, has sat idle waiting for you, or an MCP server wants input, and a Stop event every time Claude finishes responding. The terminal’s built-in alert shares the timing of the timed notification types; a Stop hook runs straight away.

Event	When it fires	Use it for
permission_prompt	Claude needs you to approve a tool use or a sandboxed command’s network request, and the prompt has waited about six seconds	”Come back and approve”
idle_prompt	Claude finished responding about 60 seconds ago and you haven’t typed since	”Done, and waiting for you”
Stop	Claude finishes responding, at the end of every turn	An instant “finished” sound
elicitation_dialog	An MCP server opens a form and you haven’t typed for about six seconds	Forms from MCP servers
auth_success	Authentication completes	Knowing a login went through

All but Stop are matcher values for the Notification hook. An empty matcher fires on every type, and the hooks guide lists the rest. In a terminal, the timed types only fire while you seem to be away, so typing holds them off. Stop is its own event and doesn’t fire when you interrupt with Ctrl+C.

1. Does my terminal already notify me?

Yes, in Ghostty and Kitty, and in iTerm2 after two settings. When Claude finishes a task or pauses for permission and you seem to be away, Claude Code sends a desktop notification in those three by default. Apple Terminal, Warp and VS Code’s integrated terminal need the bell setting or a hook.

iTerm2. Open Settings → Profiles → Terminal, check Notification Center Alerts, then click Filter Alerts and turn on Send escape sequence-generated alerts.

Other terminals. Ring the bell instead by adding this to ~/.claude/settings.json, alongside any settings already there:

{
  "preferredNotifChannel": "terminal_bell"
}

If you accepted Claude Code’s first-run setup in Apple Terminal, it turned the audible bell off; turn it back on under Settings → Profiles → Advanced → Audible bell.

Over SSH. The notification still reaches your Mac. Ghostty and Kitty forward it with no setup; iTerm2 needs the settings above.

Inside tmux. tmux swallows the notification unless passthrough is on. Add the setting and reload tmux:

echo 'set -g allow-passthrough on' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

2. How do I add a Claude Code notification hook on macOS?

Add a Notification hook to ~/.claude/settings.json that runs osascript to show a macOS banner. It runs whenever Claude Code sends a notification, alongside the terminal’s own alert rather than instead of it, so it works in any terminal. This is the macOS example from Anthropic’s hooks guide:

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

If settings.json already has a hooks key, add Notification next to the events already in it instead of replacing the whole object.

Separate alerts, plus an instant “finished” sound. This version shows one banner for permission prompts and another when Claude goes idle, and adds a Stop hook that plays the Glass sound as each turn ends:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your permission\" with title \"Claude Code\"'"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code is waiting for you\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

Stop takes no matcher and fires after every turn, so the sound can get chatty. If it does, delete the Stop block and rely on idle_prompt, which waits about 60 seconds.

If no banner appears. osascript notifications come from Script Editor. Without its permission the command fails silently, and macOS doesn’t ask. Run this once:

osascript -e 'display notification "test"'

Then open System Settings → Notifications → Script Editor, turn on Allow Notifications, and run it again to confirm.

Type /hooks in Claude Code to check the hook loaded under Notification. Hooks in ~/.claude/settings.json apply to all your projects; .claude/settings.json in a repo applies to that project and can be committed for your team.

3. Can I get Claude Code notifications on my phone?

Yes, with Remote Control. It connects the Claude app on iOS or Android, or claude.ai/code, to the Claude Code session on your Mac, and can push a notification when Claude needs a decision or finishes a long task. It needs a Claude Pro, Max, Team or Enterprise plan; API keys aren’t supported.

1. Start it. Run claude --remote-control, or /remote-control inside a running session. claude remote-control starts server mode, which serves several sessions.
2. Allow notifications. Open the Claude app once, signed in to the same account as Claude Code, and accept the notification prompt.
3. Turn push on. In /config, enable Push when actions required (permission prompts and questions), Push when Claude decides (typically when a long task finishes), or both. You can also ask in a prompt: “notify me when the tests finish”.

Worth knowing:

• On Team and Enterprise plans, an Owner must enable Remote Control first.
• Pushes are skipped while you’re typing in, or focused on, the connected terminal. To skip them whenever you’re at the Mac, set CLAUDE_CLIENT_PRESENCE_FILE to a marker file; no pushes go out while it exists.
• On iOS, Focus modes and notification summaries can delay or suppress pushes.
• Permission prompts and AskUserQuestion questions stay open until you answer.

4. Can Claude Code notifications show in the MacBook notch?

Yes. A notch app installs Claude Code hooks and shows each event as a card under the notch. Unlike a banner or a bell, you can act in place: approve or deny a permission prompt, or answer Claude’s question, and Claude Code carries on without you switching to the terminal.

FavTray, our app, does this in version 2.0.8 with four cards:

1. “Claude Code wants: tool” shows the command, file or URL with Approve and Deny; ✕ hands it back to the terminal. It arrives as soon as Claude asks, because it uses the PermissionRequest hook rather than the six-second permission_prompt. After 55 seconds, Claude Code’s own terminal prompt takes over; FavTray never approves or denies on a timeout.
2. “Claude Code asks — project” shows the question and its options. Answer opens the island’s Agents page, where you pick one, tick several or type your own. After 30 seconds, the question goes back to the terminal.
3. “Claude Code finished — project” shows the start of Claude’s last message when a turn ends.
4. “Claude Code is waiting for you” appears when Claude goes idle (idle_prompt), at most once every 2 minutes per session.

Show me on the finished and waiting cards opens that session on the Agents page (Agent Sessions), and the 26-second notch approvals video shows the flow.

• Setup: turn it on in Settings → Claude Code; your next Claude Code session picks it up. FavTray adds PermissionRequest, Stop, Notification and PreToolUse (for AskUserQuestion) hooks to ~/.claude/settings.json next to your own, backs the file up each time it installs them, and removes only its own entries when you turn it off. Requests and answers travel over a local unix socket that only your macOS user can open, so they never leave your Mac.
• Sounds: five optional cues, off by default. When on, they’re muted by default in fullscreen apps, while a screen recorder is running and during a Focus.
• No notch: the cards come from a small glass pill at the top of the screen.
• Limits: Claude Code only (Codex sessions are watched, with no cards or approvals), no jump to the terminal since you answer in place, no phone app, and it never shows other apps’ notifications.
• Plan: it’s part of FavTray Pro, on any paid plan or the 7-day free trial every install gets (pricing). The free tier doesn’t include it.

Other notch apps act on these events too, including coucou (free, MIT) and CodeIsland (free, MIT), which both also have iPhone apps, Vibe Notch (free, Apache-2.0) and Vibe Island ($19.99 once), all checked on 7 October 2026; our comparison covers how they differ.

Banner, phone or notch: which should you use?

Choose by where you’ll be when Claude needs you. At your desk, the terminal’s alert, the bell or a hook is enough. Away from it, use Remote Control. At your Mac but busy in other apps, a notch app lets you answer without switching windows.

Way	Setup	Tells you when	Can you act on it there?	Away from your Mac	Cost
Terminal notification	None in Ghostty and Kitty; two settings in iTerm2	Claude finishes or needs permission while you’re away from the terminal	No, you go back to the terminal	No	Free
Terminal bell	One setting	The same events	No	No	Free
Notification hook	Edit settings.json	Any notification type you match, and every finished turn with Stop	No	Only if your command forwards it	Free
Remote Control push	/config toggles and the Claude app	Claude needs a decision, or decides to tell you	Yes, in the Claude app	Yes	Included in Claude Pro, Max, Team and Enterprise
Notch app	Install the app, which adds hooks	Permission prompts and questions, plus other events depending on the app	Approve, deny and answer	No (some have phone apps)	Free to paid

• One terminal, at your desk: the terminal’s own notification or the bell, plus a Stop hook if you want to hear every finished turn.
• Long tasks while you’re out: Remote Control with Push when actions required on.
• Several sessions in the background: a notch app, so approvals don’t wait for you to switch windows.

What about Codex?

Codex CLI has its own settings in ~/.codex/config.toml. notify runs a program you choose whenever Codex emits a supported event, currently only agent-turn-complete. tui.notifications, in the [tui] table, turns on the terminal UI’s built-in alerts and can be limited to event types such as agent-turn-complete and approval-requested.

Codex also has hooks, including Stop and PermissionRequest, in ~/.codex/hooks.json or config.toml. The config reference and advanced config docs have the details. FavTray 2.0.8 only watches Codex sessions: they appear on its Agents page, with no cards or approvals.

Why isn’t my notification showing?

Usually it’s macOS or timing, not Claude Code: a missing notification permission, a Focus, tmux without passthrough, or a timed notification that hasn’t fired yet because you were typing or didn’t wait the 6 to 60 seconds. Check these in order:

• Script Editor can’t notify: run the osascript test above, then allow Script Editor in System Settings → Notifications.
• Your terminal can’t notify: the built-in alert needs notification permission for Ghostty, Kitty or iTerm2 itself.
• A Focus or Do Not Disturb is on: it silences banners.
• tmux is swallowing it: turn on allow-passthrough, as shown above.
• Wrong file, or invalid JSON: hooks belong in ~/.claude/settings.json or the project’s .claude/settings.json, and one stray comma breaks the file. /hooks shows what Claude Code actually loaded.
• Timing: permission_prompt waits about 6 seconds and idle_prompt about 60, and typing in the terminal holds both off. Use Stop for an instant alert.
• Apple Terminal’s bell is off: turn Audible bell back on, as in way 1.
• Remote Control: pushes are skipped while you’re at the terminal. If /config shows No mobile registered, open the Claude app so it refreshes its push token.

Start with what your terminal already does, add a hook for a banner or a sound, and reach for Remote Control or a notch app when you need to answer from somewhere other than the terminal; if you want those answers under the notch, FavTray’s Agent Sessions is one option.

Sources (checked 7 October 2026): Claude Code terminal configuration, hooks guide, hooks reference and Remote Control; Codex config reference, advanced config and hooks; coucou, CodeIsland, Vibe Notch and Vibe Island; and the FavTray changelog.