pushover-hermes-plugin

A Hermes Agent plugin that adds Pushover as a notification platform. Outbound-only — sends push notifications, no inbound message handling.

It also provides opt-in agent lifecycle notifications (finished, questions, errors, approvals, blockers) delivered via Pushover and/or native desktop notifications.

What this plugin does on your machine

• Network: sends HTTPS POST requests to https://api.pushover.net/1/messages.json (Pushover's API) with your app token, user key and the notification text. No other network calls, no telemetry.
• Notification content: when lifecycle notifications are enabled, excerpts of the agent's replies, questions, errors and terminal commands awaiting approval are sent to Pushover. Use PUSHOVER_NOTIFY_QUESTION=minimal to send generic messages instead.
• Shell commands: runs notify-send only when native notifications are enabled (PUSHOVER_NOTIFY_NATIVE=true or /notifications enable native).
• Files written: $HERMES_HOME/logs/pushover_hermes_plugin.log (plugin log), $HERMES_HOME/plugin-data/pushover-hermes-plugin/settings.json (enable/disable state saved by /notifications save), and $HERMES_HOME/.env (only when you run the interactive setup wizard).
• Background processes: none.

Requirements

• Python 3.11+
• aiohttp >= 3.9, < 4
• A Pushover account with an app token and user key
• Optional: notify-send (libnotify) for native desktop notifications

Installation

From a remote Git repository

hermes plugins install lightx/pushover-hermes-plugin --enable

From a local clone (development)

git clone https://github.com/lightx/pushover-hermes-plugin.git
cd pushover-hermes-plugin
hermes plugins install file://$(pwd) --enable

This installs the plugin and enables it in a single step. To install without enabling:

hermes plugins install file://$(pwd) --no-enable

Other plugin management commands

hermes plugins list                                  # table: enabled / disabled / not enabled
hermes plugins enable pushover-hermes-plugin         # add to allow-list
hermes plugins disable pushover-hermes-plugin        # remove from allow-list
hermes plugins update pushover-hermes-plugin         # pull latest
hermes plugins remove pushover-hermes-plugin         # uninstall

Upgrading from 1.0.x: the plugin was renamed from pushover-platform to pushover-hermes-plugin. Replace pushover-platform with pushover-hermes-plugin in plugins.enabled (config.yaml), otherwise the gateway silently skips the plugin.

After installing, restart the gateway:

hermes gateway restart --system   # or: sudo hermes gateway restart --system

Configuration

Option 1 — Environment variables (recommended)

export PUSHOVER_APP_TOKEN=your_app_token   # from pushover.net/apps
export PUSHOVER_USER_KEY=your_user_key     # from pushover.net front page

Option 2 — config.yaml

gateway:
  platforms:
    pushover:
      enabled: true
      api_key: <PUSHOVER_APP_TOKEN>
      token: <PUSHOVER_USER_KEY>
      extra:
        device: ""   # optional: restrict to a specific device name

Note: environment variables always take precedence over config.yaml values.

Option 3 — Interactive setup

hermes gateway setup

Select Pushover from the platform list. The wizard prompts for your credentials and writes them to ~/.hermes/.env.

Access control

Restrict which Pushover user keys can receive notifications:

export PUSHOVER_ALLOWED_USERS=user_key_1,user_key_2   # comma-separated
export PUSHOVER_ALLOW_ALL_USERS=true                  # disable restriction

Agent lifecycle notifications

Off by default. Enable with:

export PUSHOVER_NOTIFY_ENABLED=true     # Pushover lifecycle notifications
export PUSHOVER_NOTIFY_NATIVE=true      # native desktop notifications (notify-send)

Variable	Default	Meaning
PUSHOVER_NOTIFY_STATES	all	Space-separated subset of finished questions errors pre-approval post-approval blockers, or usual (everything except post-approval) / all
PUSHOVER_NOTIFY_QUESTION	full	Detail level: full, summary, or minimal (no agent text sent)
PUSHOVER_NOTIFY_DEVICE	—	Restrict lifecycle notifications to one Pushover device

Hooks used: post_llm_call, pre_approval_request, post_approval_response, pre_tool_call, post_tool_call.

/notifications command

/notifications status                     show current state
/notifications test pushover|native       send a test notification
/notifications enable pushover|native     turn a channel on
/notifications disable pushover|native    turn a channel off
/notifications save                       persist enable/disable state across restarts

Logging

Plugin logs are written to ~/.hermes/logs/pushover_hermes_plugin.log.

The log level defaults to logging.level from ~/.hermes/config.yaml:

logging:
  level: DEBUG   # inherited by pushover plugin

To override only for this plugin (useful for verbose debug without affecting other logs):

export PUSHOVER_LOG_LEVEL=DEBUG

After changing the log level, restart the gateway:

hermes gateway restart --system

Behaviour

• Messages are truncated to 1024 characters (Pushover API limit)
• Images are sent as a text message containing the URL and caption
• metadata["title"] is forwarded as the notification title when present
• PUSHOVER_HOME_CHANNEL (defaults to PUSHOVER_USER_KEY) is the home channel for send_message(target="pushover"), hermes send -t pushover and cron deliver=pushover; pushover:<user-or-group-key> targets a specific key
• Fire-and-forget — no reply handling

Credits

Lifecycle notifications, native notifications, the /notifications command, setup wizard and CI were contributed by Cosmin Diaconu.

License

MIT — provided as-is, no warranty.