Get notified when Claude Code needs your input

Claude Code often runs for a while - exploring code, making edits, running builds. You switch to another task, forget to check back, and waste time waiting when it was already done.

The fix: desktop notifications that pop up the moment Claude Code is ready for input or needs your permission to continue.

Built-in Notifications

Claude Code sends desktop notifications natively in Ghostty, Kitty, and iTerm2. Ghostty and Kitty need no setup at all. iTerm2 requires enabling notification forwarding:

1. Open Settings (Cmd+,)
2. Go to Profiles → Terminal
3. Check Notification Center Alerts
4. Click Filter Alerts and enable Send escape sequence-generated alerts

Running inside tmux? Add set -g allow-passthrough on to your ~/.tmux.conf, or notifications will never reach the outer terminal.

Other terminals can set "preferredNotifChannel": "terminal_bell" in your settings to ring the terminal bell instead.

For more details, see the official terminal configuration docs.

Custom Hook with terminal-notifier

Not covered by built-in notifications? Or want more control over the message and sounds? Use a Notification hook.

First, install terminal-notifier:

brew install terminal-notifier

Then add this to your ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message 'Ready for input'"
          }
        ]
      },
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message 'Permission required' -sound default"
          }
        ]
      }
    ]
  }
}

Two matchers handle different scenarios:

• idle_prompt - Claude finished working about 60 seconds ago and is waiting for your next instruction
• permission_prompt - Claude has been waiting about 6 seconds for your approval to run a command or make a change (includes a sound so you don’t miss it)

Both only fire while you’re away from the keyboard — any keystroke resets the timer, so you won’t get spammed while actively working.

For the full hooks reference, see the Claude Code hooks documentation.

Which to Choose

Ghostty, Kitty, and iTerm2 users: Use the built-in notifications. Simplest setup, no external dependencies.

Everyone else: Use the terminal-notifier hook. Works in any terminal and lets you customize the message and add sounds.