---
title: "How to know when Claude Code needs input, across every session you run"
description: "To know when Claude Code needs input, add a Notification hook on permission_prompt whose alert names the waiting session, and route it home when Claude runs over SSH."
url: "https://aldena.ai/blog/know-when-claude-code-needs-input"
---

# How to know when Claude Code needs input, across every session you run

Published 2026-11-16.

## A Notification hook tells you when Claude Code needs input

To know when Claude Code needs input, add a [Notification hook](https://code.claude.com/docs/en/hooks#notification) on the `permission_prompt` matcher, which fires once a permission prompt has waited about six seconds.

For a long time my alert system was tabbing through sessions. The usual find was one parked on a permission prompt while I read a diff in another tab, idle the whole time I thought it was working.

Claude Code also ships a built-in alert, which fires when Claude finishes a task or pauses for a permission prompt while you appear to be away. Per Anthropic's [terminal setup page](https://code.claude.com/docs/en/terminal-config), Ghostty, Kitty and iTerm2 show it as a desktop notification (iTerm2 only after you turn its alert settings on). Apple Terminal gets at most a silent bell, and other terminals get nothing. Setting `"preferredNotifChannel": "terminal_bell"` in `~/.claude/settings.json` sends the terminal bell instead, whatever the terminal.

Hooks run alongside that built-in alert rather than replacing it. You need one in Warp, the VS Code terminal or anything else outside those three, or when the alert has to reach your phone.

## Match permission_prompt and leave Stop alone

The `permission_prompt` matcher catches a tool approval or a sandboxed command's network request, and `elicitation_dialog` catches a form from an MCP server, both after about six seconds.

Those two block. Claude has stopped, and nothing moves until somebody answers. Matchers accept a pipe for alternation, so `"matcher": "permission_prompt|elicitation_dialog"` covers both in one entry.

![Table matching what Claude Code waits on to its Notification matcher, permission_prompt and elicitation_dialog after about 6 seconds, agent_needs_input, idle_prompt after about 60 seconds and the Stop event marked skip, above the settings.json hook block](https://cdn.aldena.ai/images/blog/know-when-claude-code-needs-input-1-20261116.png)

Stop is the tempting choice, and I think it is the wrong one. The Stop event runs every time Claude finishes responding, including the replies you watched arrive, so a hook on it pings you about work you already saw.

`idle_prompt` sits between the two. It fires when Claude finished about 60 seconds ago and you haven't typed since, so it is your turn and nothing is blocked. I give it a sound and no popup. If you run background sessions in agent view, add `agent_needs_input` as well. It fires when a background session starts waiting on you while agent view is open in a terminal.

An empty matcher fires on every notification type, `auth_success` included, so I keep the list explicit. The hook goes in `~/.claude/settings.json` to cover every project, or in a repository's `.claude/settings.json` to share it with everyone who clones it.

## Desktop commands for macOS, Linux and Windows

Anthropic's [hooks guide](https://code.claude.com/docs/en/hooks-guide#get-notified-when-claude-needs-input) gives one desktop notification command each for macOS, Linux and Windows, and each command has a condition where it shows nothing.

On a Mac the guide uses `osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'`. That goes through Script Editor, and it fails silently until Script Editor has notification permission, so turn that on in System Settings before you trust it.

Linux gets `notify-send 'Claude Code' 'Claude Code needs your attention'`, which needs a desktop notification daemon. Headless servers and most containers don't run one. Neither does an SSH session.

Windows is a PowerShell one-liner, `powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"`, and it opens a dialog box that can land behind your terminal. From WSL, `powershell.exe` has to be on your `PATH`. In Windows Terminal I'd skip the dialog and send an OSC 9 sequence instead, since a dialog hidden behind the window defeats the point.

For a sound on macOS, the terminal setup page uses `afplay /System/Library/Sounds/Glass.aiff`, and I put that on `idle_prompt`.

## Over SSH and inside tmux, the alert needs a route home

[Claude Code over SSH](https://aldena.ai/blog/run-claude-code-on-remote-server) runs its hooks on the remote machine, so a desktop command fires on a box with no desktop and shows nothing.

![Four routes a Claude Code Notification event can take, a desktop command that needs a desktop session, an ntfy push to a phone, a terminalSequence that needs tmux allow-passthrough, and preferredNotifChannel set for the local terminal over SSH](https://cdn.aldena.ai/images/blog/know-when-claude-code-needs-input-2-20261116.png)

The built-in alert can make the trip on its own. Set `preferredNotifChannel` to `"iterm2"`, `"kitty"` or `"ghostty"` on the remote machine, matching the terminal on your laptop, and the desktop notification reaches your local machine.

A hook gets there with an escape sequence. Hooks have no `/dev/tty`, so the hook prints JSON with a [`terminalSequence` field](https://code.claude.com/docs/en/hooks#emit-terminal-notifications) and Claude Code writes the sequence for it. The field accepts OSC 0, 1, 2, 9, 99 and 777 plus a bare BEL. OSC 9 reaches iTerm2, ConEmu, Windows Terminal and WezTerm, OSC 99 reaches Kitty, and OSC 777 reaches urxvt, Ghostty and Warp. It works only in an interactive session, and only from a hook without `async`.

My phone gets a push from `curl -d "Claude Code needs input" ntfy.sh/your-topic`, which goes through [ntfy](https://docs.ntfy.sh/) from any machine with internet access. ntfy topic names are public, so pick one nobody will guess.

Inside tmux, Anthropic's [tmux notes](https://code.claude.com/docs/en/hooks#get-terminal-notifications-inside-tmux-or-gnu-screen) say escape sequences need tmux 3.3 or later with `set -g allow-passthrough on` in `~/.tmux.conf`. With `on`, only panes tmux is showing can send them, so a session in a window you aren't looking at stays quiet. tmux 3.4 accepts `all` in place of `on` for every pane of a session you're attached to. For [Claude Code on a cloud machine](https://aldena.ai/blog/claude-code-in-the-cloud) I'd use the phone push, because it doesn't care which terminal you opened.

## A useful alert names the session that is waiting

Every Claude Code Notification event passes JSON on stdin that includes the session's `cwd` and Claude's `message`, so the alert can name the session that is waiting.

My own setup fell apart on generic text once I was [running several Claude Code agents at once](https://aldena.ai/blog/run-multiple-claude-code-agents). Two popups that both said "Claude Code needs your attention" told me two sessions were waiting and nothing about which two, and I was back to tabbing.

One `jq` call fixes it. On Linux the hook command becomes `notify-send "Claude Code" "$(jq -r '(.cwd | split("/") | last) + ": " + .message')"`, which puts the checkout's folder name in front of Claude's own message, for example "checkout-api: Claude needs your permission". Name each folder after its task and the alert reads like a line from your to-do list.

![Four Claude Code sessions with two waiting, shown once as two identical alerts that say Claude Code needs your attention and once as alerts that name checkout-api and billing-sync, built from the hook input's cwd and message](https://cdn.aldena.ai/images/blog/know-when-claude-code-needs-input-3-20261116.png)

Claude Code v2.1.295 and later go a step further for interactive sessions. They report each session's state through the [OSC 7501 Program Status Protocol](https://code.claude.com/docs/en/terminal-config#see-session-status-in-your-terminal), so a terminal that implements it can show whether that tab is working, waiting on you or done. Inside tmux it doesn't work, and a background session reports its status in agent view instead.

## How Aldena shows which agent needs you

Aldena puts every chat whose agent is waiting on a person into the [team inbox](https://aldena.ai/features/human-in-the-loop), first in the sidebar with a count, grouped by project and oldest first.

Aldena is my product, so weigh this section accordingly. For one developer at one terminal, I'd set up the hooks first. A team has a different problem. Agents across many projects stop to ask things all day, and the question belongs in a place any teammate can answer from.

An Aldena agent runs on the team's own Anthropic, OpenAI or OpenRouter API key, or on Claude Code or Codex inside the conversation's own [sandbox](https://aldena.ai/features/isolated-projects), and its questions land in that inbox either way. Every tool an agent can call carries an allow, ask or deny policy, and asking a person is the one tool that can never be switched off. A paused run is durable, so you can answer an hour later and the agent resumes with everything it had. Questions and approvals from one turn arrive together as one batch, any member of the team can answer them, and they wait seven days.

The [aldena page](https://aldena.ai/features/ai-concierge) marks a conversation waiting on your decision as needing you. Ask it what the agents are doing and it lists recent chats across projects as running, waiting on you, finished, failed or stopped, with the text of any open question. It reports only when you ask, and it doesn't watch runs in the background.

![The aldena page with four named conversations in the list, one working and one marked needs you, beside an open reply that sorts the agents into running now, waiting on a person and idle](https://cdn.aldena.ai/images/features/ai-concierge/conversations.png)

For a push outside the app, a read-only key for the [REST API](https://aldena.ai/features/rest-api) can read the team inbox. The API has no webhooks, so I'd wire it up with a small script that polls the inbox and runs your own `notify-send` or ntfy line. On the Solo plan each read endpoint allows 60 requests a minute, and a request over the limit gets a 429 with `Retry-After` and runs nothing, so a poll every 30 seconds spends only 2 of those 60.

## The setup I run

Two Claude Code Notification hooks make up my setup, one matching `permission_prompt|elicitation_dialog` for a titled desktop alert and one matching `idle_prompt` for a short sound.

Sessions on a remote machine send the permission alert to ntfy instead, since nothing there has a desktop. Stop gets no hook. I tried one for a day, and by evening I was dismissing alerts unread, including [the one permission prompt that mattered](https://aldena.ai/blog/claude-code-permission-prompts).
