Skip to content
Docs0.9GitHubInstall

Using itNotifications

Notifications

The notification worker alerts you when an agent finishes a turn, asks a question, requests approval, or fails. Routine tool calls and idle sessions don’t alert, nor do muted agents (vendetta agent mute): a muted team member’s alerts go to its manager, whose replies to them alert you only when it flags one as needing you. Their own vendetta alert and vendetta timer still sound. Alerts never send input or approve anything.

[notifications]
desktop = false       # notify-send and a notification daemon; Notification Center on macOS
include_title = false # opt in for desktop and phone: titles may contain private text
include_reply = false # opt in for desktop and phone: the start of the reply
                      # (the HUD, on this machine only, always shows both)
label = ""            # optional machine name shown in each alert
vendetta notify start   # detached; repeated starts are harmless
vendetta notify status
vendetta notify test    # send a test to every destination; needs the worker
vendetta notify stop
vendetta notify run     # foreground, for a service manager

With [plugins.hud] enabled, alerts go to its notifications card, at the bottom of its column, where each shows for a few seconds and the card keeps the recent ones; the worker keeps them in memory only, while the HUD or another plugin reads them. Without the HUD, turn on desktop or ntfy. Desktop alerts cover the HUD, so they are off unless desktop = true.

Start the worker from your graphical session so desktop alerts reach D-Bus. It applies a changed config by itself (Configuration); restart it after changing credentials.

To run it at login on Linux, write a systemd user service around vendetta notify run with Restart=always and RestartSec=5. Stop or restart it through systemctl --user, since notify stop alone would be restarted. On macOS, install.sh already runs it through launchd.

notify start logs the worker and its plugins to ~/.local/state/vendetta/notifications/worker.log; under a service manager, notify run logs to standard error, such as the systemd journal (journalctl --user -u <unit>).

The ntfy plugin pushes each alert to an ntfy topic, for your phone.

[plugins.ntfy]
url = "https://ntfy.example.com/my-protected-topic"
token = { env = "VENDETTA_NTFY_TOKEN" } # or { command = ["pass", "show", "ntfy"] }; optional
app_links = false     # tapping opens the chat in the Vendetta app
  • Use a protected topic; an obscure name is not access control. The token is read when the first alert goes out, and again a minute after a failed read.
  • Delivery needs only outbound HTTPS.
  • Self-hosted servers need upstream-base-url: "https://ntfy.sh" for timely iPhone delivery (details).
  • Alerts carry the provider, the event, and your label, and the title and start of the reply only when [notifications] enables them. They never carry prompts or paths.
  • Delivery is best-effort: alerts expire after 60 s, are tried three times, and are not replayed after downtime. A turn that ends while the worker restarts, within five minutes, is told once it is back. vendetta notify test fails when ntfy does.
  • With [plugins.app] configured, an alert waits until the agent’s chat shows what it announces, up to 12 s, so the push never beats the message.