Files
agent-estate-wiki/systems/hermes-hq-push.md
T

5.4 KiB
Raw Blame History

title, type, status, created, updated, verified_on, review_after, confidence, tags, sources
title type status created updated verified_on review_after confidence tags sources
hermes-hq-push (Hermes HQ iPhone app plugin) system active 2026-11-04 2026-11-04 2026-11-04 2026-12-04 medium
push
notifications
plugins
ios
desktop
device-access
live-hermes-plugins-list
live-plugin-manifest
live-config

hermes-hq-push (Hermes HQ iPhone app plugin)

What it is

hermes-hq-push is a standalone Hermes plugin (kind: standalone, v0.9.27, author Hermes HQ) living at ~/.hermes/plugins/hermes-hq-push/ (tree mtime 2026-11-03 11:06). It is the host-side half of the Hermes HQ iPhone app: Apple push, phone device access, the desktop-app theme, the app's Terminal page, and Grok Live voice token minting.

Its own manifest states it replaces dispatch-push, and that "its registered phones carry over."

Verified state (2026-11-04)

Check Result
hermes plugins list hermes-hq-push — enabled, 0.9.27, state user
config.yaml → plugins.enabled line 7556: - hermes-hq-push
~/.hermes/plugins/dispatch-push/ absent — and no dispatch-push reference survives in config.yaml
live tree ~/.hermes/plugins/hermes-hq-push/ (module files + dashboard/ subdir + its own test suite)
README none — the manifest description is the only prose

The replacement is therefore clean: nothing references the retired plugin, and the new one is explicitly enabled. Enablement and version are config-verified; individual hook firing was not separately captured.

Surfaces (grouped from the plugin manifest)

Push / approvals

  • Finished turns — who replied and what they said.
  • Approvals with the command shown, Approve / Deny from the lock screen.
  • A bot waiting for a password, login, code or answer — the site or the question, never the value.
  • Live Lock Screen cards: every step the bot takes (e.g. Running npm test…, the two before it, how many) is pushed to the card, sealed so only the phone can read it; the card says Done when the turn ends.
  • Tells the app which scheduled jobs a bot is still working on.

Device access (app Settings › Device Access) — contacts lookup, location, reminders and events, alarms and timers, photos, Health, motion, music, and leaving an email or text for Anthony to send. This is what backs the Conduit-style phone sharing on the Hermes HQ app.

Desktop app — adds the Hermes HQ theme; opens a shell on the host for the app's Terminal page (the login shell, as an SSH login would; plugin-data's terminal.off disables it); lets a Nous sign-in delete, archive and rename the chats it created (Hermes refuses them otherwise) and lets the desktop app open chats the app made (Hermes answers not_found otherwise); keeps a bot's Sessions list fast on a host that has run many scheduled jobs; lets the app send into a chat the desktop app has open; page previews; and keeps the app's performance log on this computer at ~/.hermes/hq-logs.

Voice — mints the app's Grok Live voice session a short-lived xAI token (subscription sign-in or XAI_API_KEY; the bearer itself never reaches the phone).

Restart guard — stops a bot's one-off macOS launchd restart job from looping (those jobs are KeepAlive, so a one-time restart re-runs forever and locks the app out), and tells a restart script which in-app chats are mid-reply so a restart can wait.

Cross-posting — on request, posts the bot's answer back to the Telegram or Discord chat a conversation came from.

Interface

  • Tools: device_contacts_search, device_request_result.
  • Hooks: pre_approval_request, post_approval_response, pre_tool_call, on_human_input_request, on_human_input_resolved, pre_llm_call, on_session_end.

Configuration

All environment variables are optional. DISPATCH_* spellings of the APNs/relay names still work.

Variable Purpose
HERMES_HQ_APNS_KEY_PATH, HERMES_HQ_APNS_KEY_ID, HERMES_HQ_APNS_TEAM_ID Direct APNs mode — path to the app's .p8 auth key, its Key ID, and the Apple Developer Team ID that owns the app. Only the app's developer has these.
HERMES_HQ_PUSH_RELAY_URL Another push relay's HTTPS URL, or off to send nothing. Unset = alerts go through the public Hermes HQ relay, sealed so it cannot read them.
HERMES_HQ_PUSH_RELAY_KEY Only for a private relay that asks for a key.

No key material is recorded on this page and none appears in the manifest — the relay key is declared password: true and is supplied by environment only.

Relationship to the other push stacks

  • systems/push-notifications documents the Cadu/Vory bridge (hermes-push, vory-push, ~/.hermes/push/hermes_push.py) — a separate stack, untouched by this plugin and still degraded.
  • dispatch-push, the previous relay plugin for the same app, is retired and fully removed (see the verification table above).

Open

  • ~/.hermes/hq-logs retention is not documented anywhere yet — check its growth before it becomes a disk item.
  • The plugin carries a very large surface under one name; if it misbehaves the manifest description is the only capability index.
  • Operational note: the plugin's pre_tool_call guard rejects any tool call whose arguments contain the literal text of a launchd one-off-restart command — writing about that command into a file is blocked too. Describe it, don't quote it.