Claude Code finishes. Your phone tells you what happened.
You give Claude a long task, switch to something else, and then keep checking back to see if it's done. Or worse — it hit a permission prompt thirty seconds in and has been sitting there ever since.
This sends a push to your phone at the two moments that actually matter, with a short summary so you can tell from the lock screen whether it's worth going back.
✅ Claude finished · my-api All three migrations applied to staging
🤚 Claude needs you · my-api Claude needs your permission to use…
The first arrives when a turn ends. The second when Claude is stuck waiting on you — and it comes in at high priority, because that one is costing you time.
You'll need Claude Code, Python 3.8+ available
as python3, and somewhere to send the notifications.
ntfy is a pub-sub notification service. You publish to a topic — just a name in a URL — and anything subscribed to that topic gets the push. Two ways to get one:
Use the public server. Go to ntfy.sh, pick a topic name,
and that's it — no account needed. Your URL is https://ntfy.sh/<your-topic>.
Topic names are the only thing protecting them, so choose something nobody
would guess (ntfy.sh/claude is effectively public). A random suffix like
claude-k7m2xq is the difference between private and not. If you'd rather have
real access control, ntfy.sh offers accounts with
reserved topics.
Or self-host it. ntfy is a single Go binary and runs comfortably on anything, including a Raspberry Pi. The self-hosting guide covers Docker, systemd and the package managers; access control covers locking topics down with users and tokens. Worth it if you don't want your work summaries transiting someone else's server — which, given these messages describe what you're building, is a reasonable thing to care about.
Either way, install the ntfy app on your phone and subscribe to the topic. There's also a web client and a desktop app if you'd rather not use a phone.
In Claude Code:
/plugin marketplace add AvAl4nch/claude-ntfy
/plugin install claude-ntfy
And tell Claude where to send things:
use https://ntfy.sh/my-topic as the ntfy server
If your server needs credentials, say so in the same breath — Claude writes them into the config for you:
my ntfy is https://ntfy.example.com/alerts, token tk_AgQdq7mVBoFD37zQ
use https://ntfy.example.com/alerts, username alice password hunter2
It merges them into ~/.claude/ntfy-notify.json without disturbing your other
settings, then confirms with --doctor — which prints Bearer (token ending 7zQ) rather than the credential itself. Two things worth knowing before you
paste a password into a chat window: that file is plaintext, not a secret
store, and anything you type to Claude lands in the session transcript. If either
bothers you, use the NTFY_CLAUDE_TOKEN or NTFY_CLAUDE_PASSWORD environment
variables instead and skip the file. An access token beats an account password
either way — it only grants publishing, and you can revoke it on its own.
That's the whole setup. The plugin wires up the hooks itself, so there's no config file to hand-edit and no paths to get right.
One thing to know: nothing gets sent until you set a topic. There's no default, deliberately — a built-in URL would mean every unconfigured install publishes to a topic somebody else owns, and ntfy topics are public by default. That's a quiet way to leak your work to strangers. Until you pick a topic, this does nothing and notes why in its log.
The plugin includes a skill, so you don't have to remember any of the settings below. Say what you want in plain English:
use https://ntfy.example.com/alerts as the ntfy server
switch the summaries to the llm one, the truncated ones read badly
stop notifying me when you just need permission
my ntfy alerts stopped working
Claude makes the change and dry-runs it before anything real gets sent. The rest of this README is for when you'd rather do it yourself.
Everything lives in ~/.claude/ntfy-notify.json:
{
"url": "https://ntfy.sh/your-topic-here",
"summarizer": "heuristic"
}| What | Config key | Environment variable | Default |
|---|---|---|---|
| Where to send | url |
NTFY_CLAUDE_URL |
none — you must set this |
| Access token | token |
NTFY_CLAUDE_TOKEN |
none |
| Username / password | username, password |
NTFY_CLAUDE_USERNAME, NTFY_CLAUDE_PASSWORD |
none |
| How credentials travel | auth_mode |
NTFY_CLAUDE_AUTH_MODE |
header |
| How summaries are written | summarizer |
NTFY_CLAUDE_SUMMARIZER |
heuristic |
A command-line flag beats an environment variable, which beats the config file.
All of ntfy's auth styles work. Pick whichever your server uses.
An access token:
{ "url": "https://ntfy.example.com/alerts", "token": "tk_AgQdq7mVBoFD37zQ" }A username and password:
{ "url": "https://ntfy.example.com/alerts", "username": "alice", "password": "hunter2" }Both go out as a normal Authorization header — Bearer for a token, Basic
for a username. That also covers the case where the auth isn't ntfy's at all but
a reverse proxy in front of it, since that's the same header.
If you paste a user:pass string into the token field by mistake, it does the
right thing and sends Basic rather than failing cryptically.
When credentials seem right but nothing arrives, some proxies, CDNs and
corporate gateways strip the Authorization header before it reaches ntfy. ntfy
has a fallback that carries it in the URL instead:
{ "auth_mode": "query" }You don't have to figure this out yourself. When --doctor sees a 401 it retries
the other way and tells you which one worked:
publish HTTP 401 Unauthorized
RETRY OK with auth_mode='query' -- your current mode is not reaching the
server (a proxy is likely stripping it). Set "auth_mode": "query" in ...
If both fail, it says that too — which means the credentials themselves are wrong, not the delivery.
Worth knowing before you reach for it: a credential in the query string can end
up in server access logs and proxy logs, where a header wouldn't. It's still sent
over TLS, so it isn't exposed in transit, but header is the better default and
query is the fallback for when the header genuinely can't get through.
One thing this can't do for you: if you lock down a topic, the ntfy app on your phone needs the same credentials. Add the server login there as well, or the app goes quiet in exactly the same undramatic way.
heuristic is the default. It strips the markdown, grabs the first real
sentence, throws away filler openers, and cuts to six words. Instant and free.
llm asks Haiku to write the summary instead. The phrasing is better — you
get whole thoughts rather than sentences cut off mid-stride — but it adds roughly ten to twenty seconds and a small token cost to every single turn. If the call fails it
quietly falls back to the heuristic.
Same input, both ways:
| Claude said | heuristic |
llm |
|---|---|---|
| "Perfect, I have fixed the failing authentication tests in the login module." | Fixed the failing authentication tests in… | Fixed failing authentication login tests |
| "| Check | Result |… All three migrations applied cleanly against staging." | All three migrations applied cleanly against… | All three migrations applied to staging |
Start with heuristic. Switch if the truncation starts bothering you.
The "needs you" notifications always use the heuristic — that text is short and fixed already, so there's nothing for a model to improve.
Start here:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ntfy_notify.py" --doctorIt'll tell you which Python it found, what topic you're configured for, which hooks are actually live, and whether it can reach your server. It publishes at minimum priority, so running it won't buzz your phone.
This matters more than it sounds, because the notifier never reports failures
out loud. If it crashed or exited non-zero it would interrupt your Claude
session, and a notifier that breaks your work is worse than one that misses a
message. So when something goes wrong it exits quietly and writes to
~/.claude/ntfy-notify.log. That silence is on purpose — --doctor and that log
are how you see behind it.
A few things it commonly catches:
| What you see | What's going on |
|---|---|
| Nothing arrives at all | No topic configured, or the plugin didn't install. --doctor says which. |
HTTP 403 in the log |
A firewall or WAF — Cloudflare especially — rejecting the request. |
HTTP 401 on a private topic |
Missing, wrong, or stripped credentials. --doctor distinguishes the three. |
| Publish says 200, phone stays quiet | It reached the server fine. Check the app is subscribed to that exact topic and allowed to notify in the background. |
| Nothing arrives, but config looks right | Hooks load when a session starts. A session already running when you installed the plugin doesn't have them — restart it. --doctor shows when the last real send was, which makes this obvious. |
You get one notification per thing that happens. Claude Code raises an "idle" event about a minute after a turn ends, which would otherwise mean a "finished" push immediately followed by a "waiting for your input" push about the same standstill. The second one is dropped. It still comes through when it's genuinely the first thing worth telling you, and any real event resets that.
Registering it twice is safe. If both the plugin hooks and hand-written
settings.json hooks are live, they fire within microseconds of each other — so
the two processes race for an atomic lock and only the winner sends. You get one
push, not two. Different events with similar wording (two permission prompts in a
row) are still told apart, because the fingerprint is taken from the raw payload
rather than the shortened summary.
Hooks load at session start. Installing or changing them doesn't affect a
session that's already running, which is the single most confusing failure here:
the config is right, --doctor finds the hooks, and nothing arrives. Restart the
session. --doctor reports the last real send so you can spot it.
It ignores the boring events. Login confirmations and quota messages fire on their own schedule and aren't worth a buzz, so only the ones needing a human get through.
It sends its own User-Agent. Cloudflare and most WAFs reject Python's default one, which shows up as a mysterious silent 403. Learned that the hard way.
It posts via ntfy's JSON API instead of the header-based one, because summaries contain em-dashes and other non-ASCII, and HTTP headers can't carry that cleanly.
No dependencies — standard library only. Read
scripts/ntfy_notify.py if you want the details; it's
one file.
If you'd rather just run the script
Clone it:
git clone https://github.com/AvAl4nch/claude-ntfy.gitAdd both hooks to ~/.claude/settings.json, merging into whatever's already
there:
{
"hooks": {
"Stop": [
{ "hooks": [ {
"type": "command", "command": "python3",
"args": ["/abs/path/to/claude-ntfy/scripts/ntfy_notify.py"],
"async": true, "timeout": 60
} ] }
],
"Notification": [
{ "hooks": [ {
"type": "command", "command": "python3",
"args": ["/abs/path/to/claude-ntfy/scripts/ntfy_notify.py"],
"async": true, "timeout": 60
} ] }
]
}
}Three details worth getting right:
- Use the
argsform rather than one long shell string — it runs the interpreter directly, so Windows paths with spaces or backslashes never hit a shell parser. - Merge carefully. A malformed
settings.jsonsilently disables everything in that file, not just this hook, so the damage from a bad edit is wider than you'd expect. - Keep
timeoutabove 45 seconds. Thellmsummarizer can take that long on a slow run, and a shorter timeout kills it mid-call — you silently get the truncated heuristic instead.
Set your topic in ~/.claude/ntfy-notify.json as described above.
To let Claude manage the settings for you, link the skill in too:
ln -s /abs/path/to/claude-ntfy/skills/ntfy-notify ~/.claude/skills/ntfy-notifyOn Windows, a junction instead:
New-Item -ItemType Junction -Path "$HOME\.claude\skills\ntfy-notify" -Target "<repo>\skills\ntfy-notify"Don't do this and install the plugin — both sets of hooks fire, and you'll get everything twice.
Dry-run prints what would be sent without sending it:
echo '{"hook_event_name":"Stop","cwd":"/p/demo","last_assistant_message":"Fixed the flaky login test."}' \
| python3 scripts/ntfy_notify.py --dry-runSend a real one:
python3 scripts/ntfy_notify.py --testRun the whole suite — 28 checks covering duplicate suppression under real concurrency, auth encoding, summary grounding, and which events stay silent:
python3 tests/run_tests.pyIt uses a throwaway local server, so it never touches a real topic.
evals/payloads.jsonl has the sample payloads it feeds through.
MIT — see LICENSE.