From your agent to your phone.
Set up Nudge, understand each alert, and find the fix when delivery stops.
Get started
- Run the installer. Run the direct installer, or hand the cookbook to an agent. You will choose an access mode, notification types, and phone. Setup needs Docker (or Colima) and Node.
- Subscribe in the ntfy app. Use the server URL and topic the installer shows. All alert types share that one topic.
- Confirm the test alert. The installer sends one to your phone before setup is complete.
Managing your install
There is no separate CLI. Re-run the installer to add an agent or update — it keeps your server and topic. Each agent keeps its settings in its own file.
| Task | How |
|---|---|
| Add an agent or update | Run sh install.sh again; the existing topic is kept. |
| Check what is wired | bash scripts/uninstall.sh --json inventory, read-only. |
| Stop notifications | bash scripts/uninstall.sh 1; the server keeps running. |
How it works
- 01
Your agent
A supported agent reports questions, permission requests, finished turns, and failures.
- 02
Nudge
The plugin classifies the event, writes a short caption, and publishes it to ntfy.
- 03
Your ntfy server
Your server receives the alert. Auth allows your token to publish while anonymous subscribers can only read.
- 04
Your phone
The ntfy app shows alerts from one topic. On iOS, a content-free wake signal helps deliver them while the app is closed.
Keep the generated topic private. Anyone who knows its name can subscribe when anonymous reading is enabled.
Notifications
Five kinds of alerts arrive on the same topic.
| Kind | When it fires | Example |
|---|---|---|
| ❓ Question | The agent asks for input, including a form prompt. | Pick environment · staging | prod |
| 🔒 Permission | The agent waits for your approval. | read · config.json |
| ✅ Finished | A turn completes without a question. | Done in 1m 52s · 9 tools |
| 🚨 Error | A session or tool call fails. Repeats collapse for 60 seconds. | shell failed · ECONNRESET |
| 📣 Custom | The agent calls the ntfy_notify tool. | Whatever the agent wrote |
Codex currently supports question, permission, and finished alerts. Error and custom alerts are available in OpenCode. Codex permission pings are muted when global Auto-review is set or Full access/never ask is reported. Codex hooks cannot see per-chat reviewer overrides.
Questions and permission requests are urgent; errors are high priority; finished alerts use the default priority. Change alert settings.
Access modes
Choose how your phone reaches your ntfy server.
| Mode | Phone needs | Works | Notes |
|---|---|---|---|
| Local | Same Wi-Fi | Home network | Plain HTTP on a trusted LAN. |
| Tailscale | Tailscale app | Anywhere | Private access with a *.ts.net TLS name. |
| Cloudflare | Nothing extra | Anywhere | Public URL through a Cloudflare Tunnel. |
If you switch modes, re-subscribe in the ntfy app using the new server URL.
Configuration
The installer writes these settings for you. OpenCode settings live in project or global opencode.json. The table below describes OpenCode options. Codex uses .codex/nudge.json with serverUrl, token, topic, and event toggles; its hooks live in .codex/hooks.json and require trust in /hooks. Command Code, Pi, and Hermes keep their own nudge.json — ~/.commandcode/nudge.json, ~/.pi/agent/nudge.json, ~/.hermes/nudge.json (project scope uses .commandcode/ and .pi/).
| Setting | What it controls |
|---|---|
serverUrl | The ntfy server Nudge publishes to. Use the address your agent can reach. |
token | Permission to publish. You can use a literal token or NTFY_TOKEN. |
baseTopic | The topic your phone subscribes to. Nudge generates one if you leave it unset. |
events | Which alert kinds are enabled, plus their priority and tags. |
If the phone uses a different URL from the agent, make sure both URLs reach the same server.
Troubleshooting
| What you see | What to check |
|---|---|
| No alerts on your phone | Check the server URL and topic in the ntfy app, then check that agent's nudge.json. In OpenCode, you can also ask for a test alert with ntfy_notify. Confirm that the event kind is enabled. |
| Publish fails with 401 or 403 | The publish token is missing or wrong. Update token or NTFY_TOKEN. |
| iOS alerts arrive only while the app is open | For a self-hosted server, check its upstream-base-url: "https://ntfy.sh" setting. |
| Alerts stopped after changing access modes | Remove the old phone subscription and add it again with the new server URL. |
Uninstall
Three cumulative levels. Level 1 removes each agent's config and stops notifications; level 2 also stops the server and tunnel, keeping data; level 3 wipes data and the plugin clone and is irreversible.
Start with the read-only inventory, then run the level you want. Level 3 needs the exact data-dir path confirmed.
curl -fsSL https://raw.githubusercontent.com/tomfc23/nudge/main/scripts/uninstall.sh -o uninstall.sh
Legacy ~/.config/ntfy-archive settings are removed by level 1. Full details: UNINSTALL.md.