---
name: ntfy
description: "Send push notifications via a self-hosted ntfy server. Use when phases complete, tasks finish, the LLM needs to ask the user a question, or any scenario where the user needs to be notified."
---

# ntfy — Push Notifications

Send push notifications to the user's device via ntfy. Use this skill whenever the user needs to be notified — phase completions, task finishes, questions requiring user input, errors, or any other event warranting attention.

## Configuration — `~/.env/pi-ntfy.env`

All ntfy credentials are stored in `~/.env/pi-ntfy.env`. If this file doesn't exist, the ntfy skill won't work.

### Required Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `NTFY_URL` | ntfy server URL | `https://ntfy.reeseapps.com` |
| `NTFY_TOKEN` | Authorization token | `tk_your_token_here` |
| `NTFY_TOPIC` | Default topic name | `pi` |

### Setting Up the Config File

Create the config file with your ntfy credentials:

```bash
mkdir -p ~/.env
cat > ~/.env/pi-ntfy.env << 'EOF'
NTFY_URL=https://ntfy.reeseapps.com
NTFY_TOKEN=tk_your_token_here
NTFY_TOPIC=pi
EOF
```

Then restrict permissions so only your user can read it:

```bash
chmod 600 ~/.env/pi-ntfy.env
```

### Loading Credentials

Before making requests, source the file:

```bash
source ~/.env/pi-ntfy.env
```

Or use it inline:

```bash
. ~/.env/pi-ntfy.env
```

### Checking Credentials

Verify the file is set up correctly:

```bash
source ~/.env/pi-ntfy.env
echo "URL: $NTFY_URL"
echo "Token: $NTFY_TOKEN"
echo "Topic: $NTFY_TOPIC"
```

## Priority Levels

Choose the priority based on urgency:

| Priority | Header Value | Use Case |
|----------|-------------|----------|
| Min      | `X-Priority: 1` | Informational, low importance |
| Low      | `X-Priority: 2` | Routine updates |
| Default  | `X-Priority: 3` | Normal notifications |
| High     | `X-Priority: 4` | Important, user should notice |
| Emergency| `X-Priority: 5` | Critical, must act immediately |

## Tags & Emojis

Use `X-Tags` to add emojis and labels. Separate multiple tags with commas:

```bash
-H "X-Tags: heavy_check_mark,done"    # ✔️ done
-H "X-Tags: rotating_light,urgent"    # 🚨 urgent
-H "X-Tags: warning,caution"          # ⚠️ caution
-H "X-Tags: tada,celebration"         # 🎉 celebration
-H "X-Tags: loudspeaker,announce"     # 📢 announcement
-H "X-Tags: question,ask"             # ❓ question
-H "X-Tags: skull,error"              # 💀 error
-H "X-Tags: computer,dev"             # 💻 development
-H "X-Tags: facepalm,issue"           # 🤦 issue
```

Common emoji tags: `tada`, `heavy_check_mark`, `rotating_light`, `warning`, `loudspeaker`, `question`, `skull`, `computer`, `facepalm`, `arrow_forward`, `one`, `-1`, `partying_face`, `triangular_flag_on_post`, `no_entry`, `cd`.

## Markdown Support

Set `X-Markdown: yes` (or `Content-Type: text/markdown`) to enable rich formatting:

```bash
-d "Phase complete! Here's what was done:

- **Feature A** — implemented
- **Feature B** — tested
- **Feature C** — deployed

See [details](https://example.com) for more."
```

Supported: **bold**, *italics*, `[links](url)`, `inline code`, ``` code blocks ```, lists, blockquotes, headings, horizontal rules.

## Click Actions

Open a URL when the notification is tapped:

```bash
-H "X-Click: https://example.com/dashboard"
```

Common patterns:
- `https://...` — opens in browser
- `mailto:user@example.com` — opens mail app
- `ntfy://ntfy.reeseapps.com/pi` — opens ntfy app directly

## Action Buttons

Add interactive buttons to the notification (JSON array):

```bash
-H "X-Actions: [{'id': '1', 'label': 'View Details', 'uri': 'https://example.com'}]"
```

Format: `[{"id": "1", "label": "Button Text", "uri": "https://url"}]`

## Message Structure Examples

### Phase Complete
```bash
. ~/.env/pi-ntfy.env

curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Phase 3 Complete" \
  -H "X-Priority: 4" \
  -H "X-Tags: heavy_check_mark,phase-3" \
  -H "X-Markdown: yes" \
  -d "**Phase 3: Authentication** completed successfully.\n\n- 12 tests passed\n- 94% coverage\n- 0 regressions"
```

### Task Finished
```bash
curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Task Done" \
  -H "X-Priority: 3" \
  -H "X-Tags: computer,task-complete" \
  -H "X-Markdown: yes" \
  -d "Task completed: implemented user login flow"
```

### Question for User
```bash
curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Question" \
  -H "X-Priority: 4" \
  -H "X-Tags: question,needs-input" \
  -H "X-Markdown: yes" \
  -H "X-Click: ${NTFY_URL}/${NTFY_TOPIC}" \
  -d "Should I proceed with the database migration? Reply 'yes' or 'no'."
```

### Error / Failure
```bash
curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Error" \
  -H "X-Priority: 5" \
  -H "X-Tags: skull,error" \
  -H "X-Markdown: yes" \
  -d "**Phase 2 failed!**\n\n`Exit code: 1`\n\n```\nError: connection refused\n```\n\nCheck logs for details."
```

### General Announcement
```bash
curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Update" \
  -H "X-Priority: 2" \
  -H "X-Tags: loudspeaker,update" \
  -H "X-Markdown: yes" \
  -d "The agent is now working on phase 4 of 7."
```

## Quick Reference

| Field | Header | Example |
|-------|--------|---------|
| URL | (in request) | `${NTFY_URL}/${NTFY_TOPIC}` |
| Token | (in Authorization) | `Bearer ${NTFY_TOKEN}` |
| Title | `X-Title` | `X-Title: Phase Complete` |
| Priority | `X-Priority` | `X-Priority: 5` (1–5) |
| Tags/Emojis | `X-Tags` | `X-Tags: tada,done` |
| Markdown | `X-Markdown` | `X-Markdown: yes` |
| Click URL | `X-Click` | `X-Click: https://...` |
| Actions | `X-Actions` | `X-Actions: [...]` |
| Body | `-d` | `**Message**` |

## Guidelines

1. **Always use markdown** (`X-Markdown: yes`) for readable, formatted messages.
2. **Choose priority wisely** — use 4–5 for questions and errors, 2–3 for routine updates.
3. **Pick appropriate tags** to convey the notification type at a glance.
4. **Keep titles concise** (1–5 words) — they appear in the notification shade.
5. **Include relevant details** in the body: phase numbers, task names, error messages.
6. **Add click actions** when the user might want to check more details.
7. **Use emergency priority (5)** only for critical failures requiring immediate attention.