📣 herdr-ntfy-notify

Stop babysitting your AI agents. Let them text you when they need help or finish the job.

A lightweight, zero-dependency Herdr v1 plugin that sends structured push notifications to your ntfy topic on terminal agent status changes (done & blocked).

---

⚡ The Cool Stuff (Features)

• 🎭 Situation-Aware Emojis: ntfy renders multi-emoji tags based on who is talking and what they did:
  • Codex gets a scroll 📜 | OMP / Pi get tools 🛠️ | Hermes gets a chat balloon 💬 | Librarian gets books 📚.
  • Success gets a check ✅ | Questions get a question mark ❓ | Errors get a cross ❌.
• 🚀 Sub-millisecond Local Bypass: Auto-detects if a local ntfy server is up (e.g. localhost:10081) and fires alerts instantly via curl bypassing TLS/network lag. Falls back to Tailscale smoothly.
• 📍 Location Pings: Pushes the exact workspace, tab, and pane ID (e.g. Loc: app · test (pane p3)), so you know exactly where to run herdr to take over.

---

⚙️ Quick Start

1. Link the Plugin

Tell your local Herdr daemon about this plugin:

herdr plugin link /opt/herdr-ntfy-notify

2. Configure

Copy the configuration template and edit it:

CONFIG_DIR="$(herdr plugin config-dir local.agent-ntfy-notify)"
cp /opt/herdr-ntfy-notify/.env.example "$CONFIG_DIR/.env"

Configure your .env variables:

HERDR_NTFY_EXTERNAL_URL=http://localhost:10081
HERDR_NTFY_LOCAL_URL=http://127.0.0.1:10081
HERDR_NTFY_TOPIC=herdr-alerts
HERDR_NTFY_ENABLED=1

3. Test Drive

Send a mock notification to verify the piping:

herdr plugin action invoke test --plugin local.agent-ntfy-notify

---

🔬 Deterministic Verification

Run the built-in test suite to see how different statuses and agent formats render:

cd /opt/herdr-ntfy-notify && node test_cases.js

📄 License

MIT License. See LICENSE for details.