bighelp plugin for Hermes

The Hermes plugin behind the bighelp iPhone app. It adds what the app needs on top of a stock Hermes host: agent boards, native cards, iPhone tools, live voice, files and wikis, and optional end-to-end encrypted notifications.

Hermes stays in charge of agents, chats, tools, approvals and scheduled tasks. The plugin runs inside Hermes' own 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's its folder, its routes under /api/plugins/loopdy/… and the loopdy: prefix on its skills. Renaming those would cut off app builds already on phones. Everything agents and people read says bighelp, and older names (hermes loopdy …, the loopdy toolset, LOOPDY_* settings) keep working.

Requirements

• Hermes 0.21.1 or later on macOS or Linux. Windows works for core features, but file, wiki and self-update features need macOS or Linux (on Windows the app says files aren't supported there yet). CI tests Hermes 0.21.1 and 0.21.2. The bighelp app supports hosts on Hermes 0.21.2 to 0.21.5.
• The bighelp app connects straight to your Hermes dashboard, over your local network or Tailscale. It signs in with the host's own login.

Install

hermes plugins install promptclickrun/bighelp-plugin --enable

Then restart the Hermes gateway and dashboard the way you normally do. The app can also install or update the plugin from its host setup screen; it installs the latest release.

To install a local checkout, commit your changes first (Hermes installs from Git), then run:

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

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

Hosts only get GitHub Releases. Merged changes are released together from time to time (.github/workflows/release.yml), so a merge alone doesn't reach hosts. The updater looks up the latest release, pins its exact commit, validates it, backs up the current copy and installs it with Hermes' own installer. It never moves a host to an older version. Your settings stay in place. It refuses to overwrite a modified install. Self-update needs macOS launchd or Linux user systemd.

The bighelp app shows when a host's plugin is out of date (Settings › Hosts) and can update it, restart the messaging gateway, and restart the Hermes process it's connected to so the new version loads. It then checks that the new version is running. The in-place restart (native-host-restart-v1) keeps the same process, so launchd, systemd and Hermes Desktop keep supervising it; chats running 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, and Feed posts can carry files to open, save and share.	Agent board
Apps tab	Files the agent recently made or changed, and the pictures and videos it delivered.	Artifacts and media
Cards	Native cards in chat: summaries, metrics, lists, timelines, charts, forms, checklists, weather, scores, stock quotes and more, via the bighelp_render_* tools. Agents can save a layout as a private card template and reuse it with fresh 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 each person saved in the app, and can ask with bighelp_people. Names are labels, not logins.	Who's talking
Secure input	An agent can ask for a password, API key or other secret with bighelp_request_secure_input. bighelp shows a masked pop-up; Hermes saves what you type to the agent's .env and the agent can use it only as $NAME in commands. The AI never sees the value. Hermes' own AI provider keys are excluded.
Agent templates	Save an agent's setup as a template and start new agents from it.
Template Catalog for agents	Agents can search bighelp's Template Catalog and fill a template with you (bighelp_templates_*). Making a new agent from a template is off until you turn on templates_allow_create_agent, and you approve each one.	Template tools
iPhone tools	iphone_health (read-only), iphone_calendar, iphone_reminders and iphone_location (where you are right now). Each is off until you allow it for a host on your phone. iphone_appearance changes bighelp's light or dark mode and chat color when you ask; it's on until you turn it off. They only work while bighelp is open and in the foreground.	iPhone tools
Live voice	Talk with your agent in real time. It uses the Codex subscription signed in on the host (or an API key); the work itself runs as a normal Hermes chat.	Live voice
Files and projects	Browse workspace folders you grant, and see a project's Git status and diffs. Read-only.	Workspace files, Project Git
Wiki	Connect a folder of Markdown notes and read or edit it from the app, using your Hermes login.	Wiki
Agents talking	When one agent asks another (hermes -p <agent> chat -q, or message_agent), the chat shows what the other agent is doing while it works, and which of its chats the exchange ran in. Read-only from the other agent's history; the app sends a hash of each message, never the words.	Agents talking
Teamwork	Off until you turn it on in the app. Every agent learns who the others are and what they do, and asks them for help instead of guessing. Saved in each agent's own Hermes settings, and taken back out when you turn it off.	Teamwork
Group chat activity	See which agents in a group chat are typing and which tools they use, live. Needs a Hermes host with the on_room_member_activity hook.	Room activity
Context usage	How much of the model's context the last request used.	Context usage
Provider usage	How much of each AI plan or balance you've used: Claude, Codex, GitHub Copilot, OpenCode, OpenRouter, DeepSeek, Nous Portal and more. Found automatically from the tools installed on the computer and the providers set up in Hermes. Read-only.	Provider usage
Workflows	Fixed steps your agents work through one after another, such as research, draft and review, with your sign-off at the end. Runs keep going on the computer when the app is closed. Nothing runs until you tap Run.	Workflows
Dev Factory	Coding workflows on your git projects: one run per project, each in its own worktree. An agent changes the code, the tests run (an agent fixes what they find), you review the changes and a pull request opens with your own GitHub sign-in.	Dev Factory
Usage activity	When your agents work (hours of the day), their messages, and each model's tokens and cost per day, for the app's Usage page. Hermes' own analytics carry the rest. Read-only.	Usage activity
Composio Connect	Lets your agents use the apps you connect in your Composio account. bighelp can add and turn on Composio Connect's MCP server in Hermes and shows if Hermes is signed in to it; Hermes' own MCP sign-in keeps the tokens.	Composio Connect
Provider sign-in	Sign in to accounts that otherwise need a terminal on the computer (GitHub Copilot, Claude Code, Claude subscriptions) from the phone. The provider's own sign-in tool runs on the computer; the phone gets only its link and code.	Provider sign-in
Generated media and files	Agent-made images, videos and files show up in chat. Hermes' own media rules decide what can be shared, and host paths are never exposed.	Agent attachments
Model names	model-names.json gives friendly model names. The app can refresh it without a plugin update.

Cards: rules for agents

• Call a card tool directly when it's visible in the current tool list. If Hermes has hidden it, use the official progressive-disclosure bridge (tool_search, tool_describe, tool_call) to run that exact tool. Never substitute a different tool.
• 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 and puts its display_markdown in the run's final reply. bighelp notifies the user with that reply, each card read as a short plain preview (the tool's optional notification_text, or one made from the card). A card tool result does not auto-forward to a later message, and rendering never notifies anyone by itself. Never script or reconstruct a card.
• Cards are display-only. Everything shown is embedded in the card, and opening one makes no network request.

What agents are told

Chats started in bighelp reach Hermes with session source bighelp (app builds from 2.3.0 build 33). For those chats the plugin adds a short brief to the agent's instructions: it's in the bighelp app, what the chat shows, which bighelp tools to use, and how scheduled jobs reach the phone. Other chats get one line pointing to the bighelp skill; scheduled runs and helpers get nothing.

The skills/ folder ships read-only guidance for agents, opened 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: posting to the agent board only when the user asks.
• custom-theme-authoring: making themes the app can import.
• bighelp-marketplace-publish: preparing a theme, card template or skill for review.

Since 3.0.0 the agent tools are named bighelp_* and live in the bighelp toolset (they were loopdy_* in loopdy). Saved tool settings and scheduled jobs that name the loopdy toolset still get these tools. Card tools take schema: "bighelp.generative_ui" or "bighelp.card"; the cards the app receives keep their original format, so older app builds still show them.

Notifications (optional)

Notifications and Live Activities are opt-in per host from the app. Chat never depends on them.

• Delivery. BuzzKit delivers to your phone. BuzzKit's sending key lives with bighelp's notification service, never on your host. Your host holds only a grant for one phone, one agent profile, the event types you chose and an expiry date.
• What you get. Replies, failed chats, finished scheduled tasks, approvals, questions from your agent and helper results. Each shows with the agent's name and picture. Tapping one opens the chat after the app checks it with your host.
• End-to-end encrypted (2.16.0 and later). The app gives its own key straight to your host. The host encrypts each notification's title, text and avatar for that phone and signs it. The notification service and BuzzKit only pass along bytes they can't read. They see the event type, the time and routing IDs. The format is in sealed_alerts.py.
• Live Activities. Lock Screen and Dynamic Island updates 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 straight from the host, as the same sealed alert, in about a second. The device keeps quiet about the chat on screen and tells the host that it got the alert. Without that answer in one second, the push goes out as usual.
• Quiet Hours. Each phone can set a daily window, such as 22:00 to 07:00, in its own time zone. In that window your host sends that phone no notifications, and it doesn't send them later. Replies stay in the chat.

More detail: Notifications.

Approvals

The app uses Hermes' own approvals. It offers exactly the choices Hermes gives (once, this session, always, or deny) and never invents one. No configuration is needed.

Commands

hermes bighelp status                     Plugin and notification status (never prints keys or tokens)
hermes bighelp update [--restart]         Install the latest release
hermes bighelp update-status              Last update result
hermes bighelp files grant|revoke|roots   Manage read-only workspace folders
hermes bighelp files list|read|status|diff
hermes bighelp wiki …                     Host-side wiki grants

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 or direct APNs. The app no longer uses any of that. The related code, settings and commands (hermes bighelp link …, provider, configure-apns, direct …) remain only so existing data and compatibility tests keep working. Don't set them up on new hosts.

Development

Run the tests with 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 \
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/ holds test vectors shared with the app, including the encrypted notification vector. CI runs the compatibility tests against each supported Hermes version.

License

Apache-2.0. The card format's constrained JSON-tree approach credits Sameer Gupta's Generative UI DSL.