1---
2name: notifying-through-ntfy
3description: Sends push notifications via ntfy.sh. Use when the user asks to be notified, says "ntfy me", or requests a notification when a task is done.
4license: GPL-3.0-or-later
5metadata:
6 author: Amolith <amolith@secluded.site>
7---
8
9Send a notification only when the user explicitly asks for one.
10
11## Environment
12
13Two environment variables are required:
14
15- `$NTFY_TOPIC_LLM` — the ntfy topic to publish to
16- `$NTFY_ACCESS_TOKEN` — bearer token for authentication
17
18If either is unset or empty, ask the user to set them before proceeding.
19
20## Headers
21
22Set headers on every notification:
23
24- **Title** (`-H "Title: ..."`) — brief, informative, sentence-case summary of what happened (e.g. "Refactored authentication middleware in rumilo")
25- **Tags** (`-H "Tags: ..."`) — comma-separated emoji shortcodes (prefer one). Must be a valid shortcode or ntfy treats it as a text tag instead of an emoji prefix.
26- **Priority** (`-H "Priority: ..."`) — integer 1–5. Only set when something went wrong; 3 is default and omitted.
27 - 1 (min) / 2 (low): quiet, no vibration
28 - 3 (default): normal notification
29 - 4 (high): long vibration burst
30 - 5 (max/urgent): very long vibration burst, may bypass Do Not Disturb
31- **Click** (`-H "Click: ..."`) — optional URL opened when the notification is tapped. If your environment provides a way to generate a link back to the current conversation or session, include it. If not, only set this header when linking to something directly relevant (a PR, a deploy, a docs page, etc.). Never fabricate a conversation URL.
32- **Delay** (`-H "X-At: ..."` or `-H "X-In: ..."`) — optional delay before the notification is delivered. Accepts durations (`30m`, `2h`, `1 day`), Unix timestamps, or natural language times (`10am`, `tomorrow 3pm`, `Tuesday 7am`). Minimum 10 seconds, maximum 3 days.
33
34## Body
35
36The body is a slightly longer, friendly paragraph saying who finished what in which project. Keep it conversational and informative — a sentence or two is plenty.
37
38## Examples
39
40```bash
41# normal success
42curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
43 -H "Title: Refactored authentication middleware in rumilo" \
44 -H "Tags: hammer_and_wrench" \
45 -d "Finished refactoring the auth middleware in rumilo. Session validation is cleaner now and all tests pass." \
46 "https://ntfy.sh/$NTFY_TOPIC_LLM"
47
48# success with a relevant click URL
49curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
50 -H "Title: Updated AUR package for kagi-ken" \
51 -H "Tags: package" \
52 -H "Click: https://aur.archlinux.org/packages/kagi-ken" \
53 -d "Bumped the kagi-ken AUR package to v0.4.2 and updated the checksums." \
54 "https://ntfy.sh/$NTFY_TOPIC_LLM"
55
56# something went wrong
57curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
58 -H "Title: Build failed in pi-mono — disk full" \
59 -H "Tags: rotating_light" \
60 -H "Priority: 4" \
61 -d "Ran into a full disk on the build server while compiling pi-mono. /var/log looks like it needs rotation. The build is blocked until there's space." \
62 "https://ntfy.sh/$NTFY_TOPIC_LLM"
63
64# urgent failure
65curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
66 -H "Title: Production database unreachable" \
67 -H "Tags: sos" \
68 -H "Priority: 5" \
69 -d "The primary Postgres instance stopped responding during a migration. Rolled back what we could, but the app is down." \
70 "https://ntfy.sh/$NTFY_TOPIC_LLM"
71
72# scheduled notification (delivered in 5 minutes)
73curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
74 -H "Title: CodeRabbit rate limit cleared" \
75 -H "Tags: hourglass" \
76 -H "X-In: 5m" \
77 -d "The rate limit has expired and you can retry the review now." \
78 "https://ntfy.sh/$NTFY_TOPIC_LLM"
79
80# scheduled for a specific time
81curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
82 -H "Title: Standup reminder" \
83 -H "Tags: alarm_clock" \
84 -H "X-At: 9am" \
85 -d "Daily standup starts in 15 minutes." \
86 "https://ntfy.sh/$NTFY_TOPIC_LLM"
87```
88
89## Alternative HTTP clients
90
91If `curl` is unavailable or blocked, use one of these instead:
92
93- **ht** (httpie-go): see [ht.md](references/ht.md)
94- **HTTPie**: see [httpie.md](references/httpie.md)
95- **wget**: see [wget.md](references/wget.md)
96- **Python**: see [python.md](references/python.md)
97- **Node.js**: see [nodejs.md](references/nodejs.md)