I start a long task in Claude Code and walk away. Sometimes it finishes. Sometimes it stops after four minutes to ask for a permission, and I find out an hour later.
Claude Code can tell your phone when either thing happens. It takes one hook and about five minutes. Below are three ways to do it, from free and scripted to a plugin. I built the third one, an iPhone app called AgentAlarm, so read that part knowing I am biased. The first two do not need it.
The two events you care about
Claude Code runs hooks: shell commands that fire on its own events. Two matter here:
-
Stopfires when Claude finishes a turn. -
Notificationfires when Claude waits for you. With the matcherpermission_promptit fires on a permission request, withelicitation_dialogon a question.
Hooks live in ~/.claude/settings.json for all projects, or in .claude/settings.json inside one project. The hook fires on the event itself, so the alert does not depend on the model remembering to send it.
Way 1: ntfy, free, five minutes
ntfy is a free, open source push service with an iPhone app.
- Install the ntfy app and subscribe to a topic with a long random name.
- Add this to
~/.claude/settings.json:
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "curl -s -m 5 -d 'Claude Code finished' ntfy.sh/your-long-random-topic" }] }
],
"Notification": [
{ "matcher": "permission_prompt|elicitation_dialog",
"hooks": [{ "type": "command", "command": "curl -s -m 5 -d 'Claude Code needs you' ntfy.sh/your-long-random-topic" }] }
]
}
}
- Start a new Claude Code session and give it something to do.
Two things to know. Anyone who knows a topic name on ntfy.sh can read it, so keep the name long and random and put nothing private in the message, or run your own ntfy server. And this version fires on every stop, also when Claude answers a one-line question while you sit at the keyboard. After a day you will want a filter.
Make it quiet: only when you are away
The filter I wanted first: alert me only if I have not touched the computer for two minutes. On a Mac the idle time is one command away. Save this as ~/.claude/notify.sh and run chmod +x ~/.claude/notify.sh:
#!/bin/bash
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd // "project"')")
idle=$(ioreg -c IOHIDSystem | awk '/HIDIdleTime/ {print int($NF/1000000000); exit}')
if [ "$idle" -ge 120 ]; then
curl -s -m 5 -d "Claude Code $1 in $project" ntfy.sh/your-long-random-topic
fi
Then point both hooks at it:
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "~/.claude/notify.sh finished" }] }
],
"Notification": [
{ "matcher": "permission_prompt|elicitation_dialog",
"hooks": [{ "type": "command", "command": "~/.claude/notify.sh 'needs you'" }] }
]
}
}
The hook gets a JSON description of the event on standard input. The script reads the working folder from it, so the message says which project is waiting. It needs jq (brew install jq if your Mac does not have it).
You can keep going from here: skip tasks shorter than a few minutes, allow one alert per five minutes. Each rule is a few more lines and a small state file.
Way 2: the Claude app, if you use Remote Control
While a Remote Control session is active, Claude Code can push to the Claude app on your phone. Open /config and turn on "Push when Claude decides" and "Push when actions required". There is nothing to install if you already work that way. It covers Claude Code only, and only in Remote Control sessions.
Way 3: AgentAlarm, the one I built
I wanted those filters without keeping a script alive on every machine, so I built them into an app. AgentAlarm is an iPhone app plus a small CLI. Its Claude Code hook does this by default:
- alerts only after two minutes without keyboard or mouse input;
- says "task finished" only when the turn ran at least three minutes;
- sends at most one alert per session every five minutes;
- puts the project folder name and the task length in the alert, never your prompt, your code or Claude's output.
Setup:
- Install AgentAlarm on your iPhone and sign in.
- In Claude Code, add the two plugins:
/plugin marketplace add achubnet/agentalarm-plugins
/plugin install agentalarm@agentalarm
/plugin marketplace add achubnet/agentalarm-hooks
/plugin install agentalarm-hooks@agentalarm-hooks
- Run
/agentalarm:setupand approve the connection on your iPhone, then/agentalarm-hooks:setupfor the hooks. It ends with a test notification on your phone.
If you prefer plain hooks to a plugin, the CLI does the same with three hook lines in settings.json. The setup guide has them.
The first plugin gives Claude tools it can use on its own, so you can also ask in the chat:
- "Remind me at 6 pm to review this PR."
- "Tell me when the tests pass."
- "Ring me if the migration fails." That one rings like an alarm, through Silent mode, until you tap Done.
The same CLI has hooks for Codex and Cursor.
What it does not do: there is no Android version, the app needs iOS 26 or later, and the CLI needs Node 18 or later. Over SSH and on Windows the hook cannot see whether you are at the keyboard, so it alerts every time. The app is free to download and Pro is optional. The source of both plugins is on GitHub: agentalarm-plugins and agentalarm-hooks.
Which one to pick
- You want free, open source or self-hosted, and you do not mind scripting: ntfy.
- You already work in Remote Control and use only Claude Code: the Claude app.
- You want the filters without writing them, reminders your agent can set, or several agents in one place: AgentAlarm.
You can also combine them. A hook can run several commands, so you can send to ntfy and to an app at once. I keep a longer comparison that also covers Pushover and Telegram.
If nothing arrives
- Run the hook command by hand in a terminal first. If the phone stays silent, the problem is not Claude Code.
- Check in iPhone Settings that the app may send notifications, and that no Focus is hiding them.
- Hooks are read when a session starts. After you edit
settings.json, start a new session. - A longer checklist: Claude Code notifications not working.
Which events would you want a hook for? I am collecting them for the next version.
I built AgentAlarm. I drafted this post with an AI assistant and checked every command in it before publishing.
Top comments (0)