---
name: notifying-through-ntfy
description: 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.
license: GPL-3.0-or-later
metadata:
  author: Amolith <amolith@secluded.site>
---

Send a notification only when the user explicitly asks for one.

## Environment

Two environment variables are required:

- `$NTFY_TOPIC_LLM` — the ntfy topic to publish to
- `$NTFY_ACCESS_TOKEN` — bearer token for authentication

If either is unset or empty, ask the user to set them before proceeding.

## Headers

Set headers on every notification:

- **Title** (`-H "Title: ..."`) — brief, informative, sentence-case summary of what happened (e.g. "Refactored authentication middleware in rumilo")
- **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.
- **Priority** (`-H "Priority: ..."`) — integer 1–5. Only set when something went wrong; 3 is default and omitted.
  - 1 (min) / 2 (low): quiet, no vibration
  - 3 (default): normal notification
  - 4 (high): long vibration burst
  - 5 (max/urgent): very long vibration burst, may bypass Do Not Disturb
- **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.
- **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.

## Body

The 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.

## Examples

```bash
# normal success
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: Refactored authentication middleware in rumilo" \
  -H "Tags: hammer_and_wrench" \
  -d "Finished refactoring the auth middleware in rumilo. Session validation is cleaner now and all tests pass." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"

# success with a relevant click URL
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: Updated AUR package for kagi-ken" \
  -H "Tags: package" \
  -H "Click: https://aur.archlinux.org/packages/kagi-ken" \
  -d "Bumped the kagi-ken AUR package to v0.4.2 and updated the checksums." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"

# something went wrong
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: Build failed in pi-mono — disk full" \
  -H "Tags: rotating_light" \
  -H "Priority: 4" \
  -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." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"

# urgent failure
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: Production database unreachable" \
  -H "Tags: sos" \
  -H "Priority: 5" \
  -d "The primary Postgres instance stopped responding during a migration. Rolled back what we could, but the app is down." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"

# scheduled notification (delivered in 5 minutes)
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: CodeRabbit rate limit cleared" \
  -H "Tags: hourglass" \
  -H "X-In: 5m" \
  -d "The rate limit has expired and you can retry the review now." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"

# scheduled for a specific time
curl -H "Authorization: Bearer $NTFY_ACCESS_TOKEN" \
  -H "Title: Standup reminder" \
  -H "Tags: alarm_clock" \
  -H "X-At: 9am" \
  -d "Daily standup starts in 15 minutes." \
  "https://ntfy.sh/$NTFY_TOPIC_LLM"
```

## Alternative HTTP clients

If `curl` is unavailable or blocked, use one of these instead:

- **ht** (httpie-go): see [ht.md](references/ht.md)
- **HTTPie**: see [httpie.md](references/httpie.md)
- **wget**: see [wget.md](references/wget.md)
- **Python**: see [python.md](references/python.md)
- **Node.js**: see [nodejs.md](references/nodejs.md)