bighelp plugin for Hermes

This Hermes plugin gives the bighelp app its extra features. The app runs on iPhone, iPad, Mac and Vision Pro. On a stock Hermes host, the plugin adds agent boards, native cards, iPhone tools, live voice, files, workflows and optional end-to-end encrypted notifications.

Hermes continues to control agents, chats, tools, approvals and scheduled tasks. The plugin runs inside the Hermes dashboard and uses its sign-in. It opens no extra ports and needs no bighelp account or public URL.

Hermes still knows the plugin by its first name, loopdy. That name is its folder, its routes under /api/plugins/loopdy/… and the loopdy: prefix on its skills. If we change these names, app builds that are already on phones stop working. Everything that agents and people read says bighelp. The older names (hermes loopdy …, the loopdy toolset, LOOPDY_* settings) continue to work.

Requirements

• Hermes 0.21.1 or later. Hosts on Hermes 0.22 also work. CI runs compatibility tests against Hermes 0.21.1 and 0.21.2 only.
• The bighelp app does not check the Hermes version. It reads the list of features that the host has (/native/context). If the host does not have a feature, the app tells you, for example "update the plugin".
• macOS or Linux. The plugin loads on native Windows, but these features need macOS or Linux:
  • notifications, Live Activities, instant alerts and Quiet Hours
  • workflows and Dev Factory
  • the Files tab and project Git
  • My Templates
  • provider sign-in
  • self-update and the in-place restart
• The app connects to the address of your Hermes dashboard, for example on your local network, through Tailscale or through a proxy. It signs in with the login of the host.

Install

The bighelp app can install the plugin when you add a host. The app installs the latest release.

A release has only the files that the plugin uses on a host. main also has the tests, the docs and the development tools. Each release is one commit on the releases branch. The commit message names the commit on main that the release comes from.

To install a release from a terminal, do these steps:

1. Find the commit of the release tag, for example v3.22.0:

   git ls-remote https://github.com/promptclickrun/bighelp-plugin refs/tags/v3.22.0
   

2. Install that commit. Hermes accepts only a full commit, not a tag name:

   hermes plugins install https://github.com/promptclickrun/bighelp-plugin --ref <commit> --enable
   

To install the newest commit on main, run:

hermes plugins install promptclickrun/bighelp-plugin --enable

This command installs main with all its files, not a release. If the app does not find the plugin, restart the Hermes gateway and dashboard.

To install a local checkout, commit your changes first, because Hermes installs from Git. Then run:

hermes plugins install "file://$PWD" --enable

hermes bighelp update does not update an install from a local checkout.

Update

hermes bighelp update            # install the latest release
hermes bighelp update --restart  # …and restart the gateway once
hermes bighelp update-status     # check the last update

An update finishes when the restarted Hermes serves the app with the new release. If another install replaced it first (for example from the bighelp app), update-status says that the update was superseded. You can then start a new update.

hermes bighelp update installs only GitHub Releases. The maintainer releases merged changes together from time to time (.github/workflows/release.yml). Thus a merge alone does not get to hosts.

Before a release, the maintainer can publish a test release, for example v3.22.0-rc.1. A test release is a GitHub pre-release. The app and hermes bighelp update do not offer it. Its release notes show the command that installs it on a test host. If nothing changes after the test release, the release uses the same commit.

The updater does these steps:

1. It finds the latest release and pins its exact commit.
2. It validates the release.
3. It makes a backup of the current copy.
4. It installs the release with the Hermes installer.

The updater installs only a version that is newer than the installed version. It does not overwrite a modified install, and your settings stay as they are. It needs launchd on macOS or user systemd on Linux. --restart restarts the gateway once. The dashboard keeps the old code until you restart it too.

The bighelp app shows when the plugin on a host is out of date (Settings › System), and it can update the plugin. For this, the app uses the Hermes plugin installer, not hermes bighelp update. Then the app can restart the messaging gateway and the Hermes process that it connects to, so that the new version loads. After that, the app makes sure that the new version runs. The in-place restart (native-host-restart-v1) keeps the same process, so launchd, systemd and Hermes Desktop continue to supervise it. Chats that run on that process stop.

What it adds

Feature	What you get in bighelp	Details
Agent board	Each agent's Feed, Ideas, Goals, Activity and approval history, next to its chat. Agents post with the bighelp_board tool. Feed posts can carry files that you can open, save and share.	Agent board
Files tab	An agent's working folder, the files that the agent made or changed recently, and the pictures and videos that it sent. Read-only. In Simple Bot mode, each bot's Files tab shows the folder of that bot. Other screens show the folder of the agent that serves the app.	Files tab
Cards	Native cards in chat: summaries, metrics, lists, timelines, charts, forms, checklists, weather, scores, stock quotes and more, through the bighelp_render_* tools. Agents show a person, place or song they found as a contact, place or music card with action buttons. Agents can save a layout as a private card template and use it again with new values.	Cards guide
Reactions	Agents can react to your messages with an emoji (bighelp_react_to_message).
Who's talking	When several people use bighelp with one host, agents see the name that each person saved in the app. Agents can ask for the names with bighelp_people. Names are labels, not logins.	Who's talking
Photo actions	Send your agent a photo of a business card or an event poster and ask for a contact or an event. The agent makes a draft (bighelp_draft_contact, bighelp_draft_event), and you check it next to the photo in bighelp before you save or discard it. Nothing goes into Contacts or Calendar until you save. Each agent has its own Photo actions settings: how to read each kind of picture, the question it asks, and the review messages. Text in a picture never counts as an instruction.	Photo actions

Hermes loads the plugin only into the agents that have it, usually only the default agent. Other agents cannot use the bighelp_* and iphone_* tools. The agent that serves the app is the agent of the Hermes dashboard that the app connects to (servingProfileId in /native/context), usually the default agent. The iphone_* tools are the exception: an agent that has the plugin can use them in its own chats, when the plugin lists native-device-tools-agents-v1.

Cards: rules for agents

• Call a card tool directly when it is visible in the current tool list. If Hermes hides it, use the official progressive-disclosure bridge (tool_search, tool_describe, tool_call) to run that exact tool. Never use a different tool instead.
• Inline card in the active chat: return the card as part of the current reply. Do not use the notification channel just to answer the current chat.
• Proactive or scheduled card (shown later in the app): a scheduled job (with deliver: "local") calls the card tool. The job puts the display_markdown of the card in the final reply of the run. bighelp notifies the user with that reply. Each card shows as a short plain preview: the optional notification_text of the tool, or a preview made from the card. A card tool result does not auto-forward to a later message, and a card never notifies anyone by itself. Never script or reconstruct a card.
• Cards are display-only. The card contains everything that it shows, and a card that you open makes no network request.

What agents are told

The app starts and opens its chats again with session source bighelp. For those chats, the plugin adds a short brief to the instructions of the agent. The brief tells the agent these things:

• that it is in the bighelp app
• what the chat shows
• which bighelp tools to use
• how scheduled jobs get to the phone

Other chats with a person get a short note about the app and the bighelp skill. Scheduled runs, helpers and other runs without a person get nothing.

The skills/ folder has read-only guidance for agents. Agents open it with skill_view("loopdy:<name>"):

• bighelp: start here. Cards, forms, Feed, Ideas and Goals, reminders and notifications, secure input, iPhone tools.
• generative-ui: when and how to use each card tool.
• bighelp-feed-and-ideas: post to the agent board only when the user asks.
• custom-theme-authoring: make themes that the app can import.

Since 3.0.0, the agent tools have bighelp_* names (before, they had loopdy_* names). The iphone_* tools keep their names. Most tools are in the bighelp toolset, which had the name loopdy. Saved tool settings and scheduled jobs that use the name loopdy still get these tools. The template tools are in the bighelp_templates toolset, and the workflow tool is in the bighelp_workflows toolset.

Card tools take schema: "bighelp.generative_ui" or "bighelp.card". The cards that the app gets keep their original format, so older app builds still show them.

Notifications (optional)

You turn on notifications in the app. Each setup is for one agent on one host. Live Activities use the same setup. Chat never needs them.

• Delivery. BuzzKit sends the notifications to your phone. The BuzzKit sending key stays with the bighelp notification service, never on your host. Your host gets a grant from the service. The grant names your phone, one agent profile and an expiry date. In the app, you choose which kinds of alerts your phone receives (Settings › Notifications).
• What you get. Replies, failed chats, scheduled tasks that finish or fail, approvals, questions from your agent, helper results and workflow runs. Messages between your agents alert you only if you turn them on. Each alert shows the name and picture of the agent. An agent without a picture gets the bighelp picture, so it still sends alerts. A workflow alert shows the name of the workflow. When you tap an alert, the app goes to that host and opens the chat. A scheduled task's alert opens the chat where your agent made the task, or the task itself when that chat is gone (with current app builds).
• End-to-end encrypted. The app gives its own key directly to your host. The host encrypts the title, text and avatar of each notification for that phone, and signs it. The notification service and BuzzKit only send on bytes that they cannot read. They see the event type, the time, the IDs of the agent and the chat, and routing IDs. The format is in sealed_alerts.py.
• Live Activities. Updates on the Lock Screen and in the Dynamic Island carry only a phase, a fixed label (such as "Your agent is working") and counts. They never include message text.
• Instant while bighelp is open. A phone, iPad or Mac with bighelp open gets each alert directly from the host that it uses, as the same sealed alert. The device does not show an alert for the chat on its screen, and it tells the host that it got the alert. If the device does not answer in one second, the host sends the push as usual.
• Quiet Hours. Each phone can set a daily window in its own time zone, for example 22:00 to 07:00. In that window, your host sends that phone no notifications, and it does not send them later. Replies stay in the chat. Live Activity updates continue.
• Channels. Each phone picks the channels it gets notifications from: every channel (iMessage, Telegram, a terminal and the rest), only bighelp, or a chosen few. Chats in bighelp always notify. A scheduled task follows where it delivers.

More detail: Notifications.

Approvals

The app uses the approvals of Hermes. It offers exactly the choices that Hermes gives (once, this session, always or deny) and never adds a choice. You do not have to configure anything.

Commands

hermes bighelp update [--restart]         Install the latest release
hermes bighelp update-status              Show the last update result
hermes bighelp files grant|revoke|roots   Manage read-only folder grants
hermes bighelp files list|read|status|diff

Folder grants are for the workspace-files API of the plugin (Workspace files). The current app does not use them. Its Files tab shows the working folder of an agent.

hermes loopdy … still works for scripts written before 3.0.0.

Legacy code

Earlier versions paired hosts through a bighelp Link account and sent notifications through a relay. The plugin no longer has that code. Link, its Direct transport, the relay and the wiki routes are gone. If an older host still has their settings, the plugin ignores them:

• At startup, the plugin removes the LOOPDY_LINK_* keys that pairing saved in .env. It does not change other lines.
• The plugin ignores the old direct setting.
• At the next start, the plugin deletes the relay rows in the notification store.
• The files that Link, Direct and the wiki routes saved stay on the host. Nothing reads them.

Some code stays for older setups and app builds. Do not configure it on new hosts:

• hermes bighelp status, provider, configure-apns, remove-apns and test: the legacy push settings. A host that has this push setup turns on the loopdy gateway platform. Scheduled tasks and approvals can then send alerts to phones that use it. For the notifications that you turn on in the app, status shows only how many grants are active (notifications).
• The agent template routes (native-agent-templates-v1) stay for older app builds. The current app uses My Templates.

Development

Run the tests with a separate Hermes checkout, a throwaway Hermes home and a temporary folder outside any Git checkout. On macOS, use /private/tmp, not /tmp.

HERMES_HOME=/private/tmp/bighelp-test-home TMPDIR=/private/tmp HERMES_DISABLE_LAZY_INSTALLS=1 \
PYTHONPATH=/path/to/hermes-agent:"$PWD":"$PWD/tests" \
  /path/to/hermes-agent/venv/bin/python -m unittest discover -s tests -v

hermes plugins doctor . --ci

fixtures/contracts/ has test vectors that the app shares, including the encrypted notification vector. When a pull request changes plugin.yaml, loopdy_plugin/ or tests/, CI runs compatibility tests against Hermes 0.21.1 and 0.21.2.

release-files.txt lists the top-level files and folders that a release has, and the ones that stay on main. If you add a top-level file or folder, add it to one of the two lists. To make and check the release files of your branch without a release, run:

python scripts/publish_release.py --export /private/tmp/bighelp-release --source HEAD

License

Apache-2.0. The constrained JSON-tree approach of the card format credits Sameer Gupta's Generative UI DSL. The default agent picture in alerts (loopdy_plugin/assets/default-agent-avatar.png) is the bighelp app icon art from the bighelp app repository, by the same owners under the same license.