Get notified when Claude Code needs approval or finishes

Claude Code sends a notification when it finishes a task or stops at a permission prompt while you seem to be away. You can show it as a desktop notification, a terminal bell, or anything a Notification hook can run. Which one you need depends on your terminal and on how many sessions you run.

1. Desktop notifications

In Ghostty, Kitty and iTerm2, Claude Code's notifications appear as desktop notifications without any setup.

In iTerm2, if they don't show up, open Settings > Profiles > Terminal, turn on Notification Center Alerts, then in Filter Alerts allow escape sequence-generated alerts. Also check that the terminal app has notification permission in your system settings.

These notifications also reach you from a remote session over SSH.

In the Claude desktop app, the Code tab sends its own desktop notification when a session finishes a task while you're not viewing it. A session you start from Dispatch on your phone sends a push notification there when it finishes or needs your approval.

If your terminal implements the OSC 7501 Program Status Protocol, Claude Code 2.1.295 or later also reports whether each interactive session is working, waiting on you or done, with nothing to turn on. Your terminal's documentation says whether it supports the protocol and where it shows the status.

2. The terminal bell

Other terminals, such as Apple Terminal, Warp or the VS Code terminal, don't get the desktop notification. Ask for a bell instead. Add this to ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

If you use tmux, add set -g allow-passthrough on to ~/.tmux.conf so the notification reaches the outer terminal.

If your sessions run inside Windows Subsystem for Linux, see Claude Code WSL notifications: get alerts on Windows for Windows Terminal bell settings and PowerShell hooks.

3. A Notification hook

A hook runs your own command when Claude needs you: a sound, a desktop banner, a message to your phone. It runs alongside the built-in notification. On a Mac, this plays a sound:

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

The Notification event has types you can match on, including permission_prompt and idle_prompt, so you can treat “needs approval” differently from “waiting for your next message”. A separate Stop hook runs when Claude finishes responding. None of the types covers Claude’s multiple-choice questions. See Know when Claude Code asks you a question or wants a plan approved for the hook that does.

If you run background sessions, agent view (claude agents, a research preview) also notifies you while it's open when one of them needs input, finishes or fails. It fires the Notification hook with the agent_needs_input or agent_completed type, so a hook script can react to those too. See Claude Code agent view: run and watch background sessions for how to start background sessions and reply to them.

To see how Notification fits alongside PreToolUse, PostToolUse, Stop and the other hook events, read Claude Code hooks: events, matchers, settings and handlers.

Which one to use

When notifications aren't enough

A notification says that a session needs you. With four sessions open, you still have to find which one, and once you dismiss the banner it's gone.

For a wider comparison of tmux, hooks, agent view, IDE panels and status pads, see How to monitor multiple Claude Code sessions.

Orbtile shows every session as its own tile on an iPhone, an Android phone or the Logitech MX Creative Keypad. A waiting session glows in its agent's alarm colour and moves to the front, the tile shows what it's asking, and you can answer supported requests from the pad: press Deny, or hold Allow for 0.6 seconds. It uses Claude Code's hooks through its own plugin, so your notifications keep working as before.

If you also run Kimi Code, see Kimi Code notifications: hooks, NotifyUser and TUI settings for how its hooks and progress updates work.