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.
 4user-invocable: true
 5license: LicenseRef-MutuaL-1.2
 6metadata:
 7  author: Amolith <amolith@secluded.site>
 8---
 9
10Send a notification only when the user explicitly asks for one.
11
12## Environment
13
14Two environment variables are required:
15
16- `$NTFY_TOPIC_LLM` — the ntfy topic to publish to
17- `$NTFY_ACCESS_TOKEN` — bearer token for authentication
18
19If either is unset or empty, ask the user to set them before proceeding.
20
21## Headers
22
23Set headers on every notification:
24
25- **Title** (`-H "Title: ..."`) — brief, informative, sentence-case summary of what happened (e.g. "Refactored authentication middleware in rumilo")
26- **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.
27- **Priority** (`-H "Priority: ..."`) — integer 1–5. Only set when something went wrong; 3 is default and omitted.
28  - 1 (min) / 2 (low): quiet, no vibration
29  - 3 (default): normal notification
30  - 4 (high): long vibration burst
31  - 5 (max/urgent): very long vibration burst, may bypass Do Not Disturb
32- **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.
33- **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.
34
35## Body
36
37The 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.
38
39## Examples
40
41```bash
42# normal success
43curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
44  -H "Title: Refactored authentication middleware in rumilo" \
45  -H "Tags: hammer_and_wrench" \
46  -d "Finished refactoring the auth middleware in rumilo. Session validation is cleaner now and all tests pass." \
47  "https://ntfy.sh/$NTFY_TOPIC_LLM"
48
49# success with a relevant click URL
50curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
51  -H "Title: Updated AUR package for kagi-ken" \
52  -H "Tags: package" \
53  -H "Click: https://aur.archlinux.org/packages/kagi-ken" \
54  -d "Bumped the kagi-ken AUR package to v0.4.2 and updated the checksums." \
55  "https://ntfy.sh/$NTFY_TOPIC_LLM"
56
57# something went wrong
58curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
59  -H "Title: Build failed in pi-mono — disk full" \
60  -H "Tags: rotating_light" \
61  -H "Priority: 4" \
62  -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." \
63  "https://ntfy.sh/$NTFY_TOPIC_LLM"
64
65# urgent failure
66curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
67  -H "Title: Production database unreachable" \
68  -H "Tags: sos" \
69  -H "Priority: 5" \
70  -d "The primary Postgres instance stopped responding during a migration. Rolled back what we could, but the app is down." \
71  "https://ntfy.sh/$NTFY_TOPIC_LLM"
72
73# scheduled notification (delivered in 5 minutes)
74curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
75  -H "Title: CodeRabbit rate limit cleared" \
76  -H "Tags: hourglass" \
77  -H "X-In: 5m" \
78  -d "The rate limit has expired and you can retry the review now." \
79  "https://ntfy.sh/$NTFY_TOPIC_LLM"
80
81# scheduled for a specific time
82curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
83  -H "Title: Standup reminder" \
84  -H "Tags: alarm_clock" \
85  -H "X-At: 9am" \
86  -d "Daily standup starts in 15 minutes." \
87  "https://ntfy.sh/$NTFY_TOPIC_LLM"
88```
89
90## Alternative HTTP clients
91
92If `curl` is unavailable or blocked, use one of these instead:
93
94- **ht** (httpie-go): see [ht.md](references/ht.md)
95- **HTTPie**: see [httpie.md](references/httpie.md)
96- **wget**: see [wget.md](references/wget.md)
97- **Python**: see [python.md](references/python.md)
98- **Node.js**: see [nodejs.md](references/nodejs.md)