How to know when Claude Code is waiting for you

What you get by default

Claude Code fires a notification event when it’s waiting on a permission prompt, or when it has finished and you seem to be away. What reaches you depends on the terminal:

Terminal	Default
Ghostty, Kitty	macOS desktop notification
iTerm2	Desktop notification, once you enable iTerm2’s alerts (below)
Apple Terminal	A bell character, silent if the profile’s audible bell is off
VS Code, Cursor, Warp, others	Nothing

If you use Ghostty or Kitty, check that the terminal is allowed to post notifications in System Settings › Notifications. That’s usually all you need.

iTerm2: turn on its alerts

Open iTerm2 › Settings › Profiles › Terminal, tick Notification Center Alerts, then click Filter Alerts and enable Send escape sequence-generated alerts.

Apple Terminal: get the bell back

Claude Code’s first-run terminal setup turns off the audible bell in your Terminal profile. To hear it again, go to Terminal › Settings › Profiles › Advanced and tick Audible bell. The same Bell section has Visual bell for a window flash and an option to bounce the Dock icon while Terminal is in the background.

To make Claude Code send the bell in every terminal, set this in ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Any terminal: a Notification hook

Hooks run a command of your choice and work in every terminal, including editor-integrated ones. This plays a sound and posts a notification only when Claude is waiting on you:

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

• permission_prompt fires when Claude wants approval for a tool call.
• idle_prompt fires when it has stopped and is waiting for your next message.
• Leave out matcher to run on every notification type.

Put it in ~/.claude/settings.json for all projects, or .claude/settings.json for one. Run /hooks in a session to confirm it’s loaded. Hooks run alongside the built-in notification, so in Ghostty you’ll get both.

For “Claude finished” rather than “Claude is stuck”, use the Stop event, which fires every time Claude finishes responding. It’s noisy for short turns, so most people prefer idle_prompt.

Several sessions at once

Notifications tell you that a session wants you, not which one. Two things help:

• Name sessions. /rename gives the session a title, which shows in the terminal tab.
• Use terminal status. Terminals that implement the OSC 7501 status protocol show each Claude Code session as working, waiting or done in their own UI, with no setup on Claude Code’s side (v2.1.295 or later). Check your terminal’s documentation for support.

Don’t let the Mac sleep mid-run

An agent waiting on a prompt doesn’t stop your Mac going to sleep. If you leave for lunch with a long task running, keep the Mac awake for that stretch (see how to keep your Mac awake), or the session will just be waiting when you get back.

Seeing it in the menu bar

Stat Space reads Claude Code’s own session status files on your Mac and marks any session that’s waiting or blocked as Needs you. It shows as an attention dot in the menu bar and an item on the Home card, whichever terminal or editor the session runs in, including the Claude desktop app. A macOS notification on each new “needs you” is optional (Settings › General › Claude Code sessions). From the session’s row, Jump to opens the terminal or editor it’s running in.

The same panel shows each session’s project, model, context use and last activity. It’s free and all local. See the Agents feature.