Why Claude Code waits for input without telling you, and the fix

Why there was no alert

Claude Code raises a notification event when it waits on you, but what reaches you depends on the terminal. With the default setting (preferredNotifChannel set to auto):

• Ghostty, Kitty and iTerm2 show a desktop notification. iTerm2 shows it only after you turn on its alert settings.
• Apple Terminal plays no sound. At most you get a silent bell, shown as a window flash or a Dock bounce if the profile has those on.
• Other terminals, including Warp and the VS Code integrated terminal, get nothing.
• Inside tmux, notifications never reach the outer terminal unless tmux passthrough is on.

The alerts are also timed for when you seem to be away. A permission prompt notifies after about six seconds without typing, and each keystroke restarts that wait. The idle notice comes about 60 seconds after Claude finishes responding, and only if you haven't typed since and no background subagent is still running.

Fix 1: ring the bell in any terminal

Set preferredNotifChannel to terminal_bell in ~/.claude/settings.json. Claude Code then rings the bell character in any terminal. The setting shows in /config as Local notifications.

{
  "preferredNotifChannel": "terminal_bell"
}

Running inside tmux? Add these lines to ~/.tmux.conf and run tmux source-file ~/.tmux.conf, so notifications pass through to the outer terminal:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Fix 2: a desktop notification from a hook

A Notification hook runs your own command whenever Claude Code raises one of these events. Hooks run alongside the built-in alert, in any terminal, and still run when you set notifications to off. On macOS, add this to ~/.claude/settings.json:

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

If nothing shows on macOS, open System Settings > Notifications and allow Script Editor: osascript sends through it and fails silently without permission. Run osascript -e 'display notification "test"' once so Script Editor appears in that list.

An empty matcher fires on every type. To treat them differently, use permission_prompt (a tool approval is waiting), idle_prompt (Claude finished and you haven't replied) or elicitation_dialog (an MCP server is asking you for input). For an alert the moment a permission prompt appears, without the six-second wait, use a PermissionRequest hook instead.

Fix 3: alerts on your phone

Remote Control connects a local Claude Code session to the Claude mobile app, which can send push notifications. Run /config and turn on Push when actions required for permission prompts and questions, and Push when Claude decides for things like a long task finishing. Pushes are skipped while you are typing in or focused on the connected terminal. Remote Control needs a claude.ai login and covers Claude Code sessions only.

Several sessions: agent view

Agent view (claude agents) is one screen for your background Claude Code sessions, grouped into Needs input, Working and Completed, with each session's latest status or question. While agent view is open in a terminal, a session that starts waiting on you fires the agent_needs_input notification, so the hook above covers it too. Agent view is a research preview.

Where Taskhold fits

Taskhold handles the other kind of stop: a question about the work, from any agent. With the workflow snippet in CLAUDE.md, Claude calls taskhold_block with one specific question instead of waiting in the terminal. The task moves to the top of the live board under Needs you, an open board tab can show a desktop notification, and you reply from any browser, including your phone. The agent reads the reply with taskhold_updates, and can take the next task while it waits.

If you need a decision from me, call taskhold_block on the task with one
specific question, then take the next todo. Check taskhold_updates between
steps for my reply.

• Permission prompts still need an answer in Claude Code. Taskhold carries questions about the work, not tool approvals.
• Taskhold doesn't wake a session that has stopped. The agent reads your reply the next time it calls taskhold_updates.
• The whole loop, with notification options, is in answering a blocked coding agent. If the agent never gets the taskhold tools, see MCP server not connecting and Taskhold troubleshooting.