Pushary Plugin for Hermes Agent

Push notifications and human-in-the-loop for Hermes Agent via Pushary.

Install

These are operator-only shell steps:

npx pushary@latest setup --agents hermes

That writes this plugin to ~/.hermes/plugins/pushary, the folder where Hermes keeps your own plugins. The folder survives hermes update. After pairing with the phone app, setup turns the plugin on with Hermes's own commands: hermes plugins enable pushary, then hermes config set to select Pushary as the approval transport. Existing credentials are reused. Connecting Hermes in the Pushary Mac app does the same.

Restart Hermes so it loads the plugin, then check it:

hermes gateway restart
npx pushary@latest doctor

If you installed it from Hermes's catalog (hermes plugins install pushary), the plugin is already present. If the install did not ask for PUSHARY_API_KEY, save it with hermes config set PUSHARY_API_KEY <your key>. Then select the approval transport below. Never install a second copy over an existing one.

Install by hand

Copy the pushary_plugin folder from this repository into Hermes's plugins folder, turn it on, and restart Hermes:

git clone --depth 1 https://github.com/Pushary/hermes-plugin-pushary /tmp/hermes-plugin-pushary
mkdir -p ~/.hermes/plugins
cp -R /tmp/hermes-plugin-pushary/pushary_plugin ~/.hermes/plugins/pushary
hermes config set security.approval.transport pushary
hermes config set security.approval.transport_fallback builtin
hermes plugins enable pushary
hermes gateway restart

Hermes v0.21.6 and later manage their own Python, and Hermes does not support installing plugins into it with pip. Only a Hermes older than v0.21.6 still runs from its own virtualenv. There, you can install the package with that virtualenv's Python and add pushary to plugins.enabled:

~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-plugin-pushary==0.9.2

Setup

The plugin reads PUSHARY_API_KEY through Hermes, which looks in the active profile's .env (~/.hermes/.env by default) and in the environment Hermes runs with. hermes config set PUSHARY_API_KEY <your key> saves it there. A copy installed from Hermes's catalog, or copied in by hand, uses only that.

A copy that npx pushary setup or the Pushary Mac app installed, and a pip install, also fall back to the key in ~/.pushary/config.json, which is where setup and the Mac app keep it.

What it reads and sends

• Network. Only pushary.com, or PUSHARY_BASE_URL when set. Session events on every turn, with a machine id. The questions you send. The approvals Hermes routes to Pushary, which carry the command (up to 4,000 characters) and its description after Hermes has redacted secrets from both. Gated tool arguments redacted by Hermes first. When Hermes marks a turn as failed, the reason it stopped, redacted the same way.
• Machine id. ~/.pushary/machine-id when it exists, so Hermes and your other agents count as one machine. Otherwise a hash of the hostname.
• Files. Messages queued in the Pushary app wait in ~/.pushary/run/hermes-commands until a turn picks them up. The plugin notes which Hermes process loaded it in plugin-data/pushary/loaded/ in the Hermes home.
• Credentials. PUSHARY_API_KEY, as described under Setup.
• Usage report. Once each time Hermes starts, the plugin reports that it loaded, with the plugin and Hermes versions. A copy from Hermes's catalog, or one copied into Hermes's plugins folder by hand, never sends it.

Tools

Approving from your phone

Hermes already detects dangerous commands and asks a human before running them. This plugin registers pushary as an approval transport, so that question goes to your phone instead of a terminal nobody is watching.

# ~/.hermes/config.yaml
security:
  approval:
    transport: pushary
    transport_fallback: builtin

Open the app to see the same four choices Hermes offers in the terminal. Hermes remembers the last two exactly as it would have:

transport_fallback: builtin is what makes this safe to leave on: if your API key is missing, or Terminal mode/no reachable device requests a local handoff, Hermes can fall back after Pushary safely withdraws its question. Cancellation or unverifiable withdrawal stops the action; a network failure while waiting does not silently reopen approval. Drop the fallback line and an unreachable Pushary becomes a denial instead.

How long your phone has depends on your delivery mode. Under Every time (push_only), the default for a new workspace, it is Hermes' own approvals.timeout (300 seconds by default), so an answer is still yours to give minutes after the notification lands. Under When I'm out (push_first), your phone has the push window, 20 seconds unless you change it, and then Hermes' own prompt takes over.

Per-tool gating (without the transport)

To gate specific tools rather than Hermes' dangerous-command set, set PUSHARY_GATE_TOOLS. This runs inside the pre_tool_call hook.

export PUSHARY_GATE_TOOLS="terminal,write_file"
export PUSHARY_GATE_TIMEOUT_MS=25000

When no phone, browser, or Slack channel is connected, Pushary says so on the create call rather than waiting, and the gate blocks with that as the reason instead of something that reads like a refusal.

The window here is bounded by Hermes, not by us. Hermes abandons any pre_tool_call callback that outlives plugins.hook_callback_timeout (30 seconds by default) and fails it closed, so the plugin clamps its own wait to fit inside that budget and returns a real answer rather than being cut off mid-wait. Raising plugins.hook_callback_timeout raises the window; the plugin reads it and follows. A Hermes old enough to have no callback timeout at all runs the hook to completion, and there the plugin uses the full window rather than shortening it for a deadline that does not exist.

When both are configured the transport wins: the hook escalates to Hermes' own approval gate, which gets the full 300-second window and the once/session/always choices, instead of holding a 30-second hook open on a network call.

For an escalated per-tool gate, Always allow creates a standing rule for the whole tool name, covering its future calls with different arguments. Choose Allow once when only the displayed call is authorized.

Auto-notifications

Each turn end is reported to Pushary. When Hermes marks a turn as failed, the report carries the reason, and the push for that turn says the run failed instead of that it finished. Tool calls that fail along the way are counted, not pushed. Set PUSHARY_AUTO_NOTIFY_SESSION_END=1 to also get one notification when a session finishes, with its tool and error counts.

Gated argument summaries, targets and the reason a turn failed use Hermes's forced secret redaction before truncation or transmission to pushary.com. If the host redactor is unavailable or fails, the detail is omitted.

Set PUSHARY_AGENT_NAME to identify this Hermes instance in notifications (e.g. "Hermes - daily-briefing"). It defaults to Hermes.

Messages from Pushary

An active Hermes session appears in the macOS notch and dashboard. A message sent there is injected into that session on its next turn. Hermes plugins cannot wake a CLI that is already idle, so the message remains queued until that session receives its next prompt.

Tests

PYTHONPATH=. python3 -m unittest discover -s tests

tests/test_hermes_contract.py checks this plugin's assumptions against the Hermes it is running inside: that every hook it registers is one Hermes fires, that the callback budget it clamps to is the one Hermes enforces, and that the approval request still carries what the transport reads. It skips where Hermes is not importable, so run it with the interpreter Hermes uses, and after a Hermes upgrade. On a Hermes older than v0.21.6, that interpreter is in its virtualenv:

PYTHONPATH=. ~/.hermes/hermes-agent/venv/bin/python3 -m unittest discover -s tests

License

MIT

Contributing

This public repository is a source snapshot maintained from Pushary's source monorepo. Open issues and pull requests here; accepted changes are applied upstream and then mirrored back. Do not publish registry releases from this mirror.

Use Python 3.10 or newer:

python -m pip install . build twine
python -m unittest discover -s . -p 'test_*.py'
python -m unittest discover -s tests -p 'test_*.py'
python -m build
python -m twine check dist/*

Host contract tests skip when Hermes is not installed. Run them in the Hermes environment after upgrading the host.

Customer answers and routing

Personal tools reach the operator on their configured phone, Mac or browser. Partner tools target a customer by external_id; the customer answers on their enrolled phone, or on a Mac they connected from that phone. For pushary_ask_end_user, read answered and value for choice/text results. approved is true only for an answered affirmative confirm; a choice or text containing “yes” does not authorize an action. Polling waits and notification routes follow server policy; never interpret silence as consent.

Encrypted conversation history

Version 0.9.0 exports the session's visible conversation through Hermes's read-only SessionDB API, including compacted ancestors and tool results. Rewound messages are removed from the phone timeline. Separate reasoning and hidden/model-only messages are excluded. The source contract is checked against Hermes v0.22.4; older incompatible schemas report an unavailable source instead of guessing.

History requires a paired phone, history enabled, and an installed Pushary Mac helper or pushary-transcript-register CLI with export authorization support. Upgrade the helper alongside the plugin; older helpers cannot authorize local exports. Reload the plugin once after upgrading an already-running Hermes process. Starting a session or its next prompt starts capture; this does not wake an idle agent. A profile/account change or opting out stops the exporter. Remote agents need the collector in their own environment. With the CLI, the Hermes key must be the key saved in ~/.pushary/config.json. The CLI's export check reads the server from the same PUSHARY_BASE_URL as the plugin, so it cannot catch a server mismatch. The CLI's uploader sends only sessions registered with its own key and server: if Hermes uses another server, the snapshot is written on this computer but never uploaded. When this computer does not allow history, the plugin logs one warning per Hermes process.

A bounded, owner-only local snapshot feeds Pushary's existing redaction and end-to-end encryption path. The snapshot limit is 5,000 source rows / 20 MB; over-limit, unreadable or unsupported sources report a failure and preserve the history already saved on the phone. Snapshots are retried across uploader restarts, and new capture epochs preserve the user's backfill choice.

The exporter reads the session again when Hermes's database changes, rewrites the snapshot only when the conversation changed, and refreshes it once a minute while the session runs, measured on the wall clock so a computer that wakes from sleep refreshes it on the next poll. A source that is too large or unsupported is read again only when the database changes or at that refresh; other read errors are retried on every poll. It asks the helper again when the account, consent or history setting files change, and at least once a minute. The Pushary plugin deletes snapshots in ~/.pushary/hermes-history that have not changed for 48 hours. It checks when a session starts or gets a prompt, at most once an hour, including while history is off.