How do I get a notification when Claude Code needs me?

Add a Notification hook to ~/.claude/settings.json that runs a desktop notification command. Claude Code fires the Notification event when Claude is waiting for input or permission.

Can I be notified only for permission prompts?

Yes. Set the hook matcher to permission_prompt. The matcher idle_prompt fires when Claude finished about 60 seconds ago and you have not typed since.

Does this work with several sessions?

The hook is global, so every session triggers it, but the generic message does not say which session. Tools that show all sessions in one place tell you which one is waiting.

Guide

Claude Code notifications: get alerted when a session needs you

By Eren Çolak, who makes Paneherd · Updated 24 October 2026

Claude Code can run a command whenever it is waiting for you. Add a Notification hook to ~/.claude/settings.json and your operating system shows an alert when Claude needs permission or has gone idle. This guide follows Anthropic's hooks guide (checked 24 October 2026).

The hook

On macOS:

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

On Linux, use "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"; it needs a desktop notification daemon, which SSH sessions and containers lack. On Windows, Anthropic's example runs powershell.exe with a Windows Forms message box, which opens a dialog rather than a corner notification and can appear behind your terminal. If you run Claude Code in WSL, powershell.exe must be reachable on your PATH.

If your settings already have a hooks key, add Notification beside the other events instead of replacing the object. Type /hooks to confirm it is listed, then test: press Shift+Tab to manual mode, ask for something that needs permission and switch windows. On macOS, if nothing appears, give Script Editor notification permission in System Settings.

Filter by type

The empty matcher fires on every notification type. Useful values:

permission_prompt: Claude needs you to approve a tool use, after the prompt has waited about six seconds in a terminal.
idle_prompt: Claude finished responding about 60 seconds ago and you have not typed since.

The problem with many sessions

A hook is global and its message is generic, so with four sessions open you learn that a session wants you, not which. You still have to hunt through terminals. Paneherd shows every pane's state (working, waiting, done) in one sidebar, collects Claude Code permission prompts from all sessions in a single inbox, and notifies you when a pane needs you, including on your phone. The inbox and notifications are Pro features; the free version has an optional sound.

A hook and Paneherd can run together. See handling permission prompts across sessions.

Frequently asked questions

Can I limit the hook to one project?

Hooks load from settings files, so put it in the project's settings instead of ~/.claude/settings.json. Anthropic's guide lists the locations.

Does it tell me when I hit a usage limit?

Claude Code has separate matchers for a task resuming after a usage limit. To watch the limit itself, use the free Usage Meter.

Install Paneherd free