89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# 📣 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](https://ntfy.sh) 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](https://github.com/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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
```dotenv
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](LICENSE) for details.
|