📣 herdr-ntfy-notify

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

A zero-dependency Herdr plugin that sends structured push notifications to your ntfy topic when agents finish or need action, even while you are viewing their tab. Requires Herdr 0.9.5+ and Node.js 22+.

Fork of zom-2018/herdr-ntfy-notify. The original plugin ID is retained to reuse existing local configuration.

---

⚡ 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. Clone over public HTTPS and link

Herdr 0.9.5's plugin install only accepts GitHub repositories. For this repository, use Git and the local plugin link command:

git clone https://git.qhack.cn/dma/herdr-ntfy-notify.git ~/herdr-ntfy-notify
herdr plugin link ~/herdr-ntfy-notify --enabled

If the upstream plugin is already installed, linking this fork replaces its registration under the same ID. Existing configuration stays in place, and only one version is registered. Do not uninstall with config/state purging.

2. Configure

Existing installations keep their .env in the plugin config directory. For a new installation only:

CONFIG_DIR="$(herdr plugin config-dir zom-2018.herdr-ntfy-notify)"
cp ~/herdr-ntfy-notify/.env.example "$CONFIG_DIR/.env"

Edit that local file; never commit your ntfy topic credentials.

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 zom-2018.herdr-ntfy-notify

---

Completion detection and limits

Herdr reports an unseen completion as done, but a viewed completion as idle. The plugin queries herdr agent get <pane> and uses completion_seq, which is independent of focus. Ordinary idle panes without a completion sequence do not generate an alert. Blocked alerts use state_change_seq.

Atomic receipt files in HERDR_PLUGIN_STATE_DIR/notification-receipts deduplicate concurrent hooks, metadata updates and read acknowledgements. Receipt keys include the server socket incarnation, terminal, status and sequence. Failed sends release their receipt so a later event may retry. No daemon restart or change to Herdr's built-in toast settings is required.

This is best-effort notification delivery, not a durable queue: a pane that closes or starts another turn before the hook queries it may no longer expose its completion. A killed hook can leave a receipt without delivery; a network failure after ntfy accepted a request can still produce duplicates. Receipts are small empty files retained for deduplication; remove old receipts only when their completions can no longer be replayed. Linux is tested; macOS/Windows are not validated for this fork.

To update a linked installation:

git -C ~/herdr-ntfy-notify pull --ff-only
herdr plugin link ~/herdr-ntfy-notify --enabled

Verification

Tests use an isolated temporary directory, a fake Herdr CLI and a loopback HTTP server. They never publish to your configured ntfy topic:

node --test test_cases.js

Coverage includes foreground/background completion, normal idle, read acknowledgements, concurrent hooks, independent terminals/servers, blocked alerts, disabled mode, malformed events, API errors and delivery retry.

📄 License

MIT License. See LICENSE for details.