Claude Code notifications with ntfy
Updated
Quick answer
ntfy sends a push to your phone from one curl line, with no account on ntfy.sh. Call it from a Stop hook and a Notification hook and you have Claude Code alerts on your phone for free. Two limits: the topic name is the only secret, and the alert is one-way, so you still walk back to the keyboard to answer.
How ntfy works
ntfy is an open source publish and subscribe service. You pick a topic name, subscribe to it in the ntfy app on your phone, and anything posted to https://ntfy.sh/<topic> arrives as a notification. On ntfy.sh, the public server, there is no sign-up for this; you can also run your own server, since the code is free software under the Apache 2.0 and GPLv2 licences. Try it before wiring it to Claude Code:
One line, from any terminal
curl -d "Hello from my terminal" ntfy.sh/your-topic-name
A message can carry a title, a priority from 1 to 5 that sets how loudly the phone rings, and tags, which ntfy shows as emoji when they match an emoji name. There are apps for Android and iOS and a web app; ntfy’s own FAQ says the iOS app is behind the Android one, so test it on your phone before you rely on it.
The hook script
Claude Code runs a Stop hook each time Claude finishes responding and a Notification hook when it waits for you. Both pass a JSON object on standard input. This script turns either one into an ntfy message with the project name in the title, and posts it as JSON, which avoids quoting problems in HTTP headers:
Save as ~/.claude/hooks/ntfy.sh, then chmod +x it
#!/bin/sh
# Claude Code hook: send a push through ntfy.sh. Reads the hook JSON on stdin.
topic=$(cat ~/.config/claude-ntfy/topic 2>/dev/null); [ -z "$topic" ] && exit 0
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
if [ "$(printf '%s' "$input" | jq -r '.hook_event_name')" = "Stop" ]; then
title="Done · $project"; prio=3
body=$(printf '%s' "$input" | jq -r '.last_assistant_message // "Finished"' | head -c 300)
else
title="Needs you · $project"; prio=4
body=$(printf '%s' "$input" | jq -r '.message // "Claude is waiting"')
fi
jq -nc --arg t "$topic" --arg ti "$title" --arg m "$body" --argjson p "$prio" \
'{topic:$t,title:$ti,message:$m,priority:$p}' \
| curl -s -m 5 -d @- https://ntfy.sh/ >/dev/null
exit 0
Merge into ~/.claude/settings.json
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/ntfy.sh", "async": true }] }
],
"Notification": [
{ "matcher": "permission_prompt|elicitation_dialog",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/ntfy.sh", "async": true }] }
]
}
}
async lets Claude Code carry on without waiting for the network. The matcher keeps the two waits that block Claude: a permission prompt and a form from an MCP server. The script needs jq and curl; run /hooks to check that both events list it. Keep in mind that Stop fires after every reply, short ones included, and that permission_prompt fires only after the prompt has waited about six seconds without a keystroke.
Keep the topic private
On ntfy.sh, topics are public. Without access control, ntfy’s documentation puts it plainly: the topic name is the password. Anyone who guesses it can read your alerts and post to your phone. So make the name long and random, and keep it out of your repositories:
Make a random topic name
mkdir -p ~/.config/claude-ntfy
printf 'claude-%s\n' "$(openssl rand -hex 12)" > ~/.config/claude-ntfy/topic
chmod 600 ~/.config/claude-ntfy/topic
cat ~/.config/claude-ntfy/topic # subscribe to this name in the ntfy app
Then think about what the alert carries. last_assistant_message is Claude’s final reply, which can quote code, file paths or error output. An ntfy server caches messages for 12 hours by default. If that is too much to hand to a public server, send only the project name, run your own ntfy server with users and access lists, or use the access control ntfy.sh offers on its paid plans.
What a one-way push leaves out
The alert tells you Claude is waiting. It doesn’t let you answer. A permission prompt still has to be approved in the terminal, a question still has to be picked there, and the next instruction still has to be typed there. For a ten-minute walk that is often fine; for a task that stalls every few minutes, it means many trips back.
ntfy does have action buttons, and an http action sends a request when tapped. A two-way loop is possible on top of it, but only if you build the rest: a server that receives the tap, and a PermissionRequest hook that waits for that server’s answer and returns it to Claude Code. That is a small service to write, host and secure.
ntfy or Monish
Pick ntfy if you want open source, a server you can run yourself, Android as well as iPhone, or the same topic for every script you own. Pick Monish if you use an iPhone and want to answer from it: a permission request arrives with the exact command and Allow and Deny, a question with its options, and a reply to a finished turn becomes Claude’s next instruction. Monish is free and needs no account; it runs on its own server and does not offer a self-hosted version. Setup is one command, curl -fsSL https://monish.cc/install.sh | sh -s, with the 6-digit code the app shows. The two can live side by side: hooks for the same event all run.
Questions
- Do I need an ntfy account?
- No. On ntfy.sh you can publish and subscribe without signing up. An account only matters for features such as access control or higher limits.
- Can someone else read my Claude Code alerts?
- Anyone who knows or guesses your topic name can subscribe to it. Use a long random name, keep it out of shared files, and leave sensitive text out of the message.
- Can I answer Claude from the ntfy notification?
- Not with this setup: the push only tells you Claude is waiting. Answering from the phone needs something that hands your decision back to Claude Code, such as a
PermissionRequesthook that waits for it. - Does it work on an iPhone?
- Yes, ntfy has an iOS app: subscribe to your topic there. ntfy’s FAQ notes that the iOS app is behind the Android one, so try it before you rely on it.
More guides
- Get notified when Claude Code finishesThe Stop hook on macOS, Windows and Linux, then on your phone.
- Claude Code alerts in Telegram, Slack or DiscordOne script, three destinations, and Claude Code channels.
- Claude Code notifications: six ways, comparedThe terminal bell, your own hooks, ntfy, Remote Control and notifier apps.
- Claude Code notifications over SSH and in tmuxAlerts from a server or a detached session, back to you.
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.