Write to agentalarm@achub.net with the last lines of the hook log (they contain no prompts or code).

Claude Code notifications not working

A notification that never arrives has one of a few causes: the hook did not run, it decided not to alert, the key was rejected, or the iPhone held it back. Go through them in this order.

Download on the App Store Plugins and CLI on GitHub

Free · iPhone with iOS 26 or later · Updated November 2, 2026

The AgentAlarm Notifications feed on an iPhone: “Task done: 42 files updated, tests pass” from a coding agent.

1. Test the phone side

npx agentalarm status     # signed in? hooks paused?
npx agentalarm test       # rings your iPhone once

If the test rings, AgentAlarm and your iPhone are fine and the cause is in the hooks. If it says you are not signed in or the key was rejected (exit code 3), copy a fresh text in the app (Settings → Connected Agents → Connect) and run npx agentalarm login "<text>" again. That text works once and expires after 30 minutes.

2. Read the hook log

Every hook run writes why it did or did not alert to ~/.local/state/agentalarm/hook.log:

tail -n 20 ~/.local/state/agentalarm/hook.log

No new lines after a Claude Code turn means the hook did not run at all: see step 4.

3. It ran but decided not to alert

Task too short: “task finished” needs a turn of at least 3 minutes. Lower it with npx agentalarm config set minTaskMinutes 1.
You were at the computer: by default it alerts only after 2 idle minutes. Turn that off in npx agentalarm setup.
Cooldown: at most one alert per session every 5 minutes.
Paused: npx agentalarm resume.
Quiet hours: rings from hooks become plain notifications.

4. The hook does not run

Plugin: type /plugin and check that agentalarm is installed and enabled.
Your own hooks: type /hooks in Claude Code to see what it loaded, and check that ~/.claude/settings.json is valid JSON.
Run node -v: the CLI needs Node 18 or later, and npx must be on the PATH Claude Code sees.

5. The iPhone holds it back

Settings → Notifications → AgentAlarm: allow notifications and Time Sensitive Notifications.
A Focus can hold back normal notifications: allow AgentAlarm in that Focus.
Rings need the Alarms permission: in the app, open Settings → Permissions.
Open the app once after installing or updating it so your iPhone is registered. More on the Support page.

Using the Claude app’s push instead?

Claude Code’s own push to the Claude app works only while a Remote Control session is active, and only with Push when Claude decides or Push when actions required turned on in /config. If /config says No mobile registered, open the Claude app on your phone.

Questions

Why did the task finish without a notification?

Most often the turn was shorter than 3 minutes or you were still at the computer. The hook log says which.

Why does it notify but not ring?

Hooks send quiet notifications. Only urgent alerts ring: ask Claude to “ring me when it’s done”, or set ringOnDecision to true. Quiet hours turn rings into notifications.

Does it work over SSH or in a container?

Yes, the hooks run where Claude Code runs. That machine needs internet access and its own npx agentalarm login.

Still stuck?

Write to [email protected] with the last lines of the hook log (they contain no prompts or code).