Claude Code notifications not working: five causes
Updated
Quick answer
When a Claude Code notification never shows, the cause is almost always one of five: the hook is not loaded, the JSON in settings.json is invalid, the command fails silently, the event you chose does not fire in your setup, or the system is hiding the alert. Run /hooks, then claude --debug, and test the command by hand.
Is the hook loaded
Type /hooks at the Claude Code prompt. It lists every hook the session loaded, grouped by event. If yours is missing, the problem is in the file, not in the command:
- Invalid JSON. Trailing commas and comments are not allowed. Run
jq . ~/.claude/settings.json: an error message there means Claude Code can’t read it either. - Two
hookskeys. If you pasted an example below an existing"hooks"block, the file now has two, and only one survives. Each event must be a key inside a singlehooksobject. - The wrong file.
~/.claude/settings.jsonholds hooks for every project,.claude/settings.jsonat the root of a repository holds that project’s. In a folder you haven’t trusted yet, an interactive session waits for the trust dialog before it runs the project’s hooks. - A missed change. Claude Code normally picks up edits by itself. If the hook doesn’t appear after a few seconds, restart the session.
- Your organization’s rules. If
/hooksshowsOnly hooks from managed settings run here, managed settings allow no hooks of your own.
Does it run
A listed hook may still fail every time without telling you. A failed hook on an event such as Notification shows no error in the transcript at all. Ask for the details:
Start Claude Code with a debug log you can follow
claude --debug-file /tmp/claude.log
# in another terminal
tail -f /tmp/claude.log
Trigger the event, then look for your hook in the log. If you started without the flag, /debug turns logging on mid-session and tells you where the log is. Press Ctrl+O for the transcript view, where a hook that failed on most other events shows a hook error notice with its exit status.
Does the command work by hand
Most broken hooks are broken scripts. Feed yours the kind of JSON Claude Code sends and watch what happens:
Run the hook yourself
echo '{"hook_event_name":"Notification","notification_type":"permission_prompt","message":"test","cwd":"'"$PWD"'"}' \
| ~/.claude/hooks/notify.sh
echo $?
- Permission denied: the script isn’t executable. Run
chmod +xon it. - command not found: use an absolute path, or
${CLAUDE_PROJECT_DIR}for a script inside the project.jq: command not foundmeansjqisn’t installed. - It works by hand but not from Claude Code: the hook gets Claude Code’s environment, not your shell’s. When Claude Code starts from an IDE or the desktop app, the PATH may lack what your shell profile adds; use full paths.
- On Windows, a message that mentions Git Bash means Claude Code didn’t find it to run a shell-form hook. Install Git for Windows, or switch the hook to exec form with an
argsarray. - For hooks that return JSON, anything your shell profile prints before it, such as a greeting
echo, makes Claude Code ignore the JSON.
Is it the right event
A hook can be loaded and correct, and still wait for an event that doesn’t come when you expect it.
Notificationwaits until you look away.permission_promptfires once a prompt has waited about six seconds without a keystroke, and each keystroke pushes it back.idle_promptfires about sixty seconds after Claude finishes, only if you haven’t typed since and no background agent is still running. Testing at the keyboard, you may never see either.Stopdoesn’t run when you interrupt Claude with Esc. A turn that ends on an API error firesStopFailureinstead.- Matchers are case-sensitive and must match the tool name or notification type exactly:
permission_prompt, notPermissionPrompt. - Permission hooks need a prompt. In
bypassPermissionsmode nothing is asked, and inautomode little is, so aPermissionRequesthook has nothing to fire on. - In the VS Code extension panel,
permission_promptdid not fire before Claude Code v2.1.233; on later versions it fires about six seconds after the request.PermissionRequestfires as soon as Claude asks.
Is the system hiding it
The hook ran and the command succeeded, but nothing appeared. The operating system decided that.
- macOS:
osascriptnotifications come from Script Editor. If Script Editor isn’t allowed to notify, the command fails silently and macOS never asks: turn it on in System Settings › Notifications › Script Editor. Also check Focus. - Linux:
notify-sendneeds a notification daemon. Headless servers, SSH sessions and most containers have none. - Windows: the PowerShell example in Anthropic’s docs opens a message box, which can open behind your terminal.
- Terminal notifications: iTerm2 shows them only once its alert settings are on, and inside tmux they need
allow-passthrough. - iPhone: a Focus or a scheduled summary can hold a push back. Check Settings › Notifications for the app that should ring.
With Monish: monish status
If you use Monish, start with two commands on the computer:
On the computer where Claude Code runs
monish status
monish test
The first checks the setup on that computer. The second tests the whole path: it sends a test request to your iPhone and prints what you answered, or that no answer came. If something is off, run the install command again with a new 6-digit code from the app. Then run through the iPhone side: notifications allowed for Monish in Settings, the Focus you have on, and the quiet hours and Live Activities set in the app’s Settings. While you’re typing in the terminal, a request arrives as a silent note on purpose, so test from a few steps away. The support page lists the rest.
Questions
- Why does my Notification hook fire so late?
- By design:
permission_promptwaits about six seconds without a keystroke,idle_promptabout sixty seconds after Claude finishes. For a signal at once, usePermissionRequestorStop. - Why doesn’t my Stop hook run when I press Esc?
Stopdoesn’t run when you interrupt Claude. A turn that ends on an API error firesStopFailureinstead.- Why does /hooks show nothing when my file looks right?
- Usually invalid JSON, such as a trailing comma, or two
hookskeys in one file. If the JSON is valid, restart the session, and check whether your organization allows only managed hooks. - Why does my osascript notification never show on macOS?
- macOS shows it as coming from Script Editor, and drops it silently if Script Editor isn’t allowed to notify. Turn notifications on for Script Editor in System Settings.
More guides
- Claude Code hooks explained, with examplesThe events, where they live, and which ones matter for notifications.
- The Claude Code Notification hookWhen it fires, what notification_type means, and why it waits six seconds.
- The Claude Code Stop hookRun a command when Claude finishes, or send it back to work without a loop.
- Claude Code push notifications not working on iPhoneWhat Remote Control needs, and six things to check.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.