Notify Me Setup

---
name: notify-me-setup
description: Set up or change notify-me — the plugin that pings the user's phone (via ntfy) and/or plays a sound when an agent is blocked or finished. Use when the user says "set up notify-me", "set up notifications", "notify me when you're blocked", "call me back when you need me", "change the alert sound", "turn the chime on/off", "change my ntfy topic", or when a SessionStart note reports notify-me is installed but not configured.
---

# notify-me setup

This skill configures the `notify-me` plugin by writing `~/.notify-me/config`, which the
notification hook reads. Run the whole flow in plain chat. Do NOT use a popup/AskUserQuestion —
present every choice as lettered text options in the message and wait for a typed reply.

## Config file format

Write `~/.notify-me/config` as sourceable shell `KEY="value"` lines:

```
TOKEN="user-chosen-secret"   # this IS the ntfy "topic" you subscribe to on your phone
SOUND="on"
SOUND_FILE="/System/Library/Sounds/Glass.aiff"
NOTIFY_ON_STOP="off"
SERVER="https://ntfy.sh"
```

Field meaning:
- `TOKEN` — the private secret the phone subscribes to. In the ntfy app this value is called the "topic". Acts as a password, so it must be random/unguessable.
- `SOUND` — `on`/`off`. Whether to play a local sound on this computer.
- `SOUND_FILE` — absolute path to a sound file, OR the literal `@system` to play the OS's currently-selected alert sound (macOS "beep" / Windows beep). A real file path is more reliable than `@system`, because `@system` follows the separate OS "alert volume" which is easy to leave at zero.
- `NOTIFY_ON_STOP` — `on`/`off`. If `on`, also alert when the agent finishes a turn (fires often — default `off`).
- `SERVER` — ntfy server base URL. Leave as `https://ntfy.sh` unless the user self-hosts.

## First-run / setup flow

If `~/.notify-me/config` already exists, read it and show current settings first, then ask which field to change. Otherwise run full onboarding:

### Step 1 — pick the alert sound list (from THIS machine)
Run the bundled scanner to list sounds actually present on the user's computer:
```
bash "${CLAUDE_PLUGIN_ROOT}/scripts/list-sounds.sh"
```
Present the returned files as a lettered list (label by filename, e.g. "A) Glass  B) Ping  C) Submarine ..."). Offer to preview any sound before choosing — on macOS preview with `afplay "<path>"`. Let the user pick one, or pick a sensible default (Glass on macOS) if they don't care — prefer a real file over `@system` for reliability. Always offer `@system` as one option for users who'd rather have the alert follow whatever sound they pick in their OS sound settings (warn that it depends on the OS "alert volume"). If the scanner returns nothing (e.g. Windows, or an unusual setup), offer `@system`, ask for an absolute path to a sound file, or set `SOUND="off"` (phone push still works).

### Step 2 — sound on or off by default
Ask whether the local computer sound should be `on` or `off`. (Phone push still works either way.)

### Step 3 — phone token (ntfy "topic")
Ask the user to either supply a token or let you generate one. If generating, make it random and unguessable, e.g.:
```
echo "notify-$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 10)"
```
Explain plainly: this token IS the password — anyone who knows it can read or send to it on the public ntfy.sh server, so it must stay private. Note that the ntfy phone app calls this same value a "topic".

### Step 4 — write the config
Create the directory and write the file:
```
mkdir -p "$HOME/.notify-me"
```
Write the five fields with the chosen values. Always append the inline comment `# this IS the ntfy "topic" you subscribe to on your phone` to the TOKEN line so the user can recognize it later. Set `NOTIFY_ON_STOP="off"` unless the user asks to also be pinged on every turn end.

### Step 5 — phone app guidance
Tell the user, in plain language, to finish the phone side:
1. Install the **ntfy** app (iOS App Store / Android Play Store).
2. Add a subscription using the exact TOKEN value from the config (the app labels this field "topic").
3. The sound the phone plays is controlled inside the ntfy app's per-topic settings — set it there (this plugin can't set the phone's sound from the computer).

### Step 6 — test
Offer to send a test ping so the user can confirm both the local sound and the phone push:
```
echo '{"message":"notify-me test — you should hear a sound and get a phone push."}' | bash "${CLAUDE_PLUGIN_ROOT}/scripts/notify.sh" blocked
```
Tell them to check their phone. If nothing arrives, re-check that the phone subscribed to the same topic and that the device has network.

## Sending a task-aware ping (for the agent, during work)
The automatic push shows a generic line. To make it say, in plain language, *what* you need, leave a
one-line note right before you pause for a decision — write it in the user's language, plain words, no jargon:
```
bash "${CLAUDE_PLUGIN_ROOT}/scripts/note.sh" "Editing your config — confirm whether to overwrite the old file?"
```
The next push uses that note as its body, then clears it. Use this whenever you stop and genuinely
need the user, so the phone tells them why, not just that.

## Changing settings later
Re-read `~/.notify-me/config`, show current values, edit only the field the user names, rewrite the file.

## Uninstalling
To remove user settings: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/uninstall.sh"` (deletes `~/.notify-me`). To remove the hook + scripts entirely, the user disables or uninstalls the `notify-me` plugin in their app.