All plugins

hermes-mini

A mobile-first chat app for your own Hermes agent, served from the Hermes dashboard and installable to the home screen: several chats, an inbox for scheduled-job results, live narration of what the agent is doing, to-dos, a schedules panel, a model and provider picker, dictation through Hermes' speech-to-text, and opt-in Web Push. Disclosure — serves a web app and routes from the dashboard behind its login (no own port); registers an in-process hermes-mini gateway platform for job delivery; in app chats only, adds a turn rule and job-delivery default to the prompt, appends a progress-update request to tool results during long turns, and blocks edits to its own files; writes the live narration line with small auxiliary-model calls on the user's provider; writes platforms.hermes-mini.home_channel to config.yaml once; lets the user answer an approval from a push notification; runs ffmpeg for audio metadata, hermes gateway restart -y --detach plus a dashboard restart from its Restart button, and, for the optional computer view's clipboard, a Tk helper and xclip; uses internal Hermes modules for dictation and the computer view, which may stop working after a Hermes update; opt-in Web Push to FCM/Mozilla/Apple push services; no telemetry.

ieatcode4breakfastWebv0.2.1Updated 3 days ago

About

A mobile-first chat app for your own Hermes agent, served from the Hermes dashboard and installable to the home screen: several chats, an inbox for scheduled-job results, live narration of what the agent is doing, to-dos, a schedules panel, a model and provider picker, dictation through Hermes' speech-to-text, and opt-in Web Push. Disclosure — serves a web app and routes from the dashboard behind its login (no own port); registers an in-process hermes-mini gateway platform for job delivery; in app chats only, adds a turn rule and job-delivery default to the prompt, appends a progress-update request to tool results during long turns, and blocks edits to its own files; writes the live narration line with small auxiliary-model calls on the user's provider; writes platforms.hermes-mini.home_channel to config.yaml once; lets the user answer an approval from a push notification; runs ffmpeg for audio metadata, hermes gateway restart -y --detach plus a dashboard restart from its Restart button, and, for the optional computer view's clipboard, a Tk helper and xclip; uses internal Hermes modules for dictation and the computer view, which may stop working after a Hermes update; opt-in Web Push to FCM/Mozilla/Apple push services; no telemetry.

Hermes Mini

A mobile-first chat app for your own Hermes agent.

Hermes Mini is a single Hermes plugin that serves a fast, installable web app for talking to your
agent from a phone, tablet or desktop: multiple chats, an inbox, to-dos, live progress lines,
steering, optional push notifications, dictation, and an optional bundled view of your agent's
desktop.

  • Product name: Hermes Mini (the install name and the app's own label; the browser tab shows the
    agent's name).
  • Agent name: the name your Hermes bot already has — the default profile's bot title first, then
    the serving profile's — with Hermes as the fallback when none is set.
  • One plugin: settings and state live outside the plugin, so updating the code never touches them.

Screenshots

Screenshots use sample data.

Automatic messages

Mini suppresses routine gateway lifecycle notices and first-time command tips delivered through
its bridge. App-only turn instructions discourage unsolicited introductions and profile offers
in existing and new chats. The known legacy introduction is hidden in live replies, history,
inbox and push previews. This is a narrow compatibility filter, not a general classifier of
model-written introductions. Failure templates retain a short explanation without unsupported
slash commands. Original assistant transcripts remain unchanged; filtered bridge deliveries are
not stored. Quoted examples and code are preserved. Other Hermes interfaces are unaffected.

Requirements

Hermes Agentv0.23.0 tested (commit 2bd378ed1b8d). The plugin uses documented plugin, dashboard and state APIs.
PythonWhatever Hermes runs (Hermes v0.23.0 ships Python 3.14 here; 3.11+ is expected to work).
BrowserA current Chrome, Safari, Firefox or Edge. The app is a plain ES-module page with no build step. Thoroughly tested on Android (Chrome, installed to the home screen); not yet tested on iPhone or iPad (see Verified, and not).
Optionalcryptography + httpx for push; Pillow for image dimension checks; a Hermes-configured speech-to-text provider for dictation; Hermes' Bot Desktop for the computer view.

Nothing in this list is installed by the plugin. Optional pieces degrade to a hidden control, never
a broken app.

Install

The simplest way to install Hermes Mini is to copy this prompt and send it to your Hermes agent:

Install the Hermes Mini plugin for me:
1. Run: hermes plugins install ieatcode4breakfast/hermes-mini --enable
2. Check that `hermes plugins list` shows hermes-mini as enabled.
3. Tell me the address to open: my dashboard's address followed by
   /dashboard-plugins/hermes-mini/index.html
4. Last, restart the Hermes dashboard and gateway the way they normally
   run on this machine, so the plugin loads. If you're not sure how they
   run, tell me the commands instead of guessing.

Hermes asks you to approve the commands. It tells you the address before it restarts anything,
because restarting the gateway ends its reply. Then open the address, sign in with your usual
Hermes login, and use your browser's "Install app" / "Add to Home Screen".

This needs an agent that can run hermes commands on the machine Hermes runs on, and that machine
must be able to reach GitHub. If the agent's terminal is sandboxed (a Docker or remote terminal
backend), or your Hermes install is managed or read-only, use the manual install below.

Manual install

Hermes Mini is a directory plugin: plugin.yaml plus register(ctx) (hooks) plus a
dashboard/ folder (the app page and its backend routes). Put the folder where Hermes looks for
user plugins and enable it:

cp -r hermes-mini "$HERMES_HOME/plugins/hermes-mini"
hermes plugins list                  # shows: hermes-mini  not enabled
hermes plugins enable hermes-mini    # shows: enabled

$HERMES_HOME is your Hermes home (usually ~/.hermes; a profile home is
~/.hermes/profiles/<name>). This install path was verified end to end: a plain directory drop-in
is discovered by Hermes, reported as not enabled, then becomes enabled and is listed as a user
plugin.

Check that Hermes accepts it before enabling:

hermes plugins doctor "$HERMES_HOME/plugins/hermes-mini" --ci
hermes plugins validate "$HERMES_HOME/plugins/hermes-mini"

If your Hermes build supports installing from a local Git checkout, that also works and additionally
records install provenance:

git clone /path/to/hermes-mini /path/to/hermes-mini.git   # or use your own checkout
hermes plugins install file:///path/to/hermes-mini.git --no-enable
hermes plugins enable hermes-mini

This route needs a Git repository, so it does not apply to a plain copied folder (a project
downloaded without a .git directory).

Remove it with hermes plugins remove hermes-mini, or by deleting the directory. That removes the
code; your settings, picture and app data are left in place (see
Settings, state and profiles).

Open the app

Hermes serves dashboard plugins from the dashboard process. Start it (this is the ordinary Hermes
dashboard, not something Hermes Mini adds):

hermes dashboard

Then open:

http://127.0.0.1:9119/dashboard-plugins/hermes-mini/index.html

Use --host/--port if you started the dashboard differently; the path after the origin is fixed
by the plugin's folder name. Hermes' dashboard authentication (its normal session cookie, or an
OAuth/reverse-proxy gate you have configured) protects the page and every /api/plugins/hermes-mini/
route. Bookmark it, or use your browser's "Install app" / "Add to Home Screen".

You do not need to open the default dashboard page first. If the dashboard was already running when you enabled the plugin,
restart it (and the gateway, which loads the plugin's hooks) so it picks the plugin up. When the page asks
you to sign in, Hermes' login page brings you back to the app afterwards.

First run

There is none. Open the app and it is ready to use: the header and composer take the name Hermes
already has for the bot — the default profile's bot title, then the serving profile's, then its
display name or a named profile id, and finally Hermes. The app never renames the agent, and
nothing on the page asks for a name or picture of its own.

If Hermes has no model configured yet, there is no reply to show until one is connected from the
model tab or in Hermes; history, to-dos and the inbox still work.

Reading the page and every capability probe are pure reads. Opening the app may create its own
state files under $HERMES_HOME/data/hermes-mini/, and it records the default delivery target once
(see Settings, state and profiles).

Configure a model

Use the model tab on the input box: it lists Hermes's connected providers and their models, lets a
pick switch the chat (and become the default for new chats), and sets the reasoning level and, where
the model supports it, fast mode. Providers + lists every provider Hermes supports and saves or
updates an API key through Hermes. A provider that signs in with an account, and a custom endpoint, cannot
be connected from the app: its card says to run hermes model on the computer (tap the command to copy
it). Everything goes
through Hermes's own gateway methods, and the app keeps no model state.

You can also use Hermes itself, for example hermes model or the dashboard's Config page. See the
Hermes documentation. Until a model is configured,
there is no reply to show.

What's in it

  • Chats: multiple conversations, a main chat, new chat, rename, pin (with a shared manual
    order), delete, reset of the main chat, and a read-only view of a chat that belongs to another
    source.
  • Inbox: every agent message across the app's chats, newest first, with unread tracking. A swipe
    on a phone or an envelope button on hover marks a message read or unread without opening it; a
    reply's action row in the chat (and its long-press menu) offers Mark unread, which becomes Mark
    read while the reply is held unread. The main chat's messages carry the same home icon as the chat
    list.
  • To-dos: one shared list, nesting one level, drag to sort, clear finished.
  • Schedules: the agent's scheduled jobs (Hermes cron), each with what it is, when it runs in plain
    words and when it runs next; a job running now says so. Each row's ⋮ menu pauses, resumes or deletes
    the job through Hermes' own routes, or adds it to the message being written as an inline pill, which
    reaches the agent as [Schedule: <name> · job <id>].
  • Tools tray: the hammer-and-screwdriver button folds the Schedules, Computer and To-do buttons
    away under it and brings them back; folded is the default, remembered per device. On a computer, while
    the computer view is open, its button stays out under Tools even when the tray is folded.
  • Model and provider picker: a tab on the input box's top edge shows the chat's model and reasoning
    level. The sheet lists Hermes's connected providers and their models (search, prices where Hermes
    has them), with a five-bar reasoning level meter and fast mode where the model supports it; a pick
    switches the chat and becomes the default for new chats. Providers + can add or update a
    provider's API key through Hermes.
  • Live streaming: replies appear as they arrive, with a short quiet narration line (a soft
    shimmer slides across it while the agent works) and tool-step progress. Narration uses Hermes' auxiliary model slots and stays silent if that is not
    configured.
  • Steering: send while a reply is running to steer the current turn.
  • Approvals and questions: answer them in the app; an approval can also be approved or denied
    from its notification.
  • Attachments: photos, files and pasted text, with a collapsed view for long pastes. Pictures the
    agent sends with MEDIA: show inline; audio plays inline in a voice-note player (play/pause, a
    waveform to tap or drag, download; the waveform needs ffmpeg, on PATH or in Hermes' tools
    directory); other files arrive as cards that download only when tapped. A picture that cannot be
    loaded (a missing file, a dead web link) shows its alt text instead.
  • Picture viewer: full screen, with a back button and a download button; swipe, the arrows or
    the arrow keys slide between a message's pictures; pinch or double-tap to zoom.
  • Markdown: GitHub-flavoured markdown with sanitised HTML and syntax highlighting.
  • Edit and branch: edit and resend your message, or branch a conversation.
  • Dictation: record and insert at the caret, through whatever speech-to-text provider Hermes is
    configured to use.
  • Notifications (optional): Web Push for approvals, questions and finished replies, with
    per-chat mute. A notification stays until it is tapped or swiped away.
  • Scheduled job results: Hermes cron output can be posted into the main chat or a chosen side
    chat, with a push.
  • Computer (optional): a phone-friendly live view of your agent's desktop, with take-over,
    hand-back, a trackpad and clipboard, gated by Hermes' own display tickets and control lease.

Optional features and how they degrade

FeatureNeedsWithout it
DictationAn STT provider configured in Hermes; a browser that can record.The microphone is hidden. The /dictate route also answers with a clear message.
Notificationscryptography and httpx importable by Hermes, a browser with Push, and your click on the bell.The bell is hidden. Chat is unaffected.
ComputerHermes' Bot Desktop supported and installed on this host (tools.bot_desktop).The computer button is hidden. Chat and to-dos still work.
Live narrationA Hermes auxiliary model (Hermes' title_generation inheritance).The narration line is simply absent.

A failed capability probe makes the app keep the control visible rather than hide something that
might work. The server always enforces the real rule: a disabled feature returns an error, it does
not quietly succeed.

What it touches

Hermes Mini is a community plugin, not a Nous Research product. Everything it does goes through Hermes'
plugin surfaces; this is the full list of what it reads, writes, runs and sends.

Serves

  • A web app from your Hermes dashboard: static files under /dashboard-plugins/hermes-mini/ and routes
    under /api/plugins/hermes-mini/, behind the dashboard's own login. It opens no port of its own.
  • A chat platform named hermes-mini inside the gateway (in-process), so scheduled jobs can deliver
    their results to the app.

Hooks (app chats only; other chats, Discord, the CLI, cron runs and subagents are left alone)

  • pre_llm_call: adds a short turn rule to app chats (acknowledge the newest message before the first
    tool call) and the default delivery target for scheduled jobs created there.
  • transform_tool_result: during a long turn, appends a one-line instruction to a tool result asking the
    agent for a 1–2 sentence progress update (about every few minutes or every few tools).
  • post_llm_call, pre_approval_request, on_human_input_request: queue a push notification for a
    finished reply, an approval waiting for you, or a question the agent asks — only when you have turned
    notifications on.
  • pre_tool_call: blocks an app chat from editing the plugin's own files (a self-edit guard).

Reads

  • Hermes' chat history and session list (state.db, through SessionDB; the Inbox query opens it read-only),
    the scheduled-job list
    (Hermes' cron routes), the model/provider list, and its own data folder.

Writes

  • Its own settings in $HERMES_HOME/hermes-mini/ and state in $HERMES_HOME/data/hermes-mini/.
  • $HERMES_HOME/config.yaml, once, through Hermes' config API: it records
    platforms.hermes-mini.home_channel when none is set (and marks the platform enabled if it has no
    enabled key). Nothing else there.

Runs

  • ffmpeg (from PATH or Hermes' tools folder) to read the length and waveform of an audio attachment.
  • The Restart button runs hermes gateway restart -y --detach and then restarts the dashboard, as the same user,
    only when you press it (at most once a minute).
  • With the optional computer view: a short Python helper (Tk) to copy text out of the desktop, and xclip
    to paste a picture into it.

Model calls

  • The live narration line is written by Hermes' auxiliary model (the same slot Hermes uses for chat
    titles), with a short prompt built from the tool steps of the current turn — a few small calls per turn,
    at most 80 tokens each, on your provider and your bill. Without an auxiliary model the line is absent.

Sends over the network

  • Web Push messages to your browser's push service (Google FCM, Mozilla or Apple), only after you turn
    notifications on, and only to those hosts. The push key is created at that moment.
  • Dictation audio to the speech-to-text provider you configured in Hermes (through Hermes).
  • Nothing else: no telemetry, no analytics, no update checks.

Settings, state and profiles

The plugin directory is replaceable code. Everything you change lives outside it, under the Hermes
home of the profile serving the request, resolved with Hermes' own helper at request time:

PathContents
$HERMES_HOME/hermes-mini/config.yamlYour agent name, home label, uploaded picture's filename, first-run completion, optional public URL and push contact.
$HERMES_HOME/hermes-mini/assets/Your uploaded picture.
$HERMES_HOME/data/hermes-mini/App state: to-dos, pin order, seen markers, inbox read state, the app-chat registry and recorded main-chat id, push key, subscriptions and muted chats.

config.yaml is written atomically with mode 0600, and unknown keys are dropped. Everything is
per profile: a second Hermes profile gets its own name, picture and data, and one profile's app never
reads another's.

The plugin also records the platform's delivery default in Hermes' own $HERMES_HOME/config.yaml:
platforms.hermes-mini.home_channel, and in that same first write it marks the platform enabled if
it has no enabled key. The app records its main chat there the first time it loads, so a bare
hermes-mini job address has a destination. The home channel is written only when no value is
present; an existing value is never replaced.

The app's own registry, $HERMES_HOME/data/hermes-mini/app-chats.json, also records the main chat's
id. That id, not the chat's name, is how the app and scheduled-job delivery find the home.

Every app chat carries a built-in turn rule: acknowledge the newest message and say in one line
what happens next before starting work. It rides along with every user message in an app chat
only
(and its subagents), never in Discord, cron, or another channel.

The plugin also contributes two system-prompt sections to app chats only: hermes-mini.app
describes the app, its chats, scheduled-job delivery and image handling; hermes-mini.style keeps
replies plain — the point first, no code or file paths, no jargon unless explicitly asked. Other
surfaces — Discord, cron, the terminal — never receive them.

An optional file at $HERMES_HOME/data/hermes-mini/app-instructions.md is appended to that rule.
Use it for extra operator instructions; the built-in acknowledgement stays.

During a long turn, the plugin also asks the agent for a short progress update every four minutes,
or every ten tool calls, so a phone user is not left watching a silent screen. It applies to app
chats only and skips delegated subagents.

Push notifications

Turning notifications on is the only thing that creates the VAPID key pair, and it happens the first
time you press the bell and confirm. The key and your subscription stay in
$HERMES_HOME/data/hermes-mini/push/. Only known push services (FCM, Mozilla, Apple, Windows) are
accepted as subscription endpoints, and the request must be HTTPS.

The VAPID sub claim uses, in order: your configured push contact, your configured public URL,
Hermes' configured dashboard/gateway public URL, then a reserved .invalid fallback. No personal
domain is baked into the source.

A notification stays until it is tapped or swiped away. Reading its chat in the app does not close
it: on many Android launchers an app closing its own notification leaves the icon's count behind,
and a web app cannot correct that count.

Scheduled job results

A Hermes scheduled job can post its result into the app. Address it as:

  • hermes-mini:main — the main chat.
  • hermes-mini:<chat id> — a specific chat, stable across renames.
  • hermes-mini:<chat name> — a named chat, when the name is unique. The spelling's case does not
    matter.
  • hermes-mini — the same as hermes-mini:main.

main and home are reserved words for the main chat, so a side chat with either name is reached
by its id, not its name.

The result is stored as a normal message in that chat and pushes a notification. The plugin gives
the app a default delivery chat the first time it loads, so no setup is needed. The home itself is
recorded by id in the app registry: renaming another chat to Hermes Mini cannot take it, and
resetting the main chat records the replacement id.

A name is a label, not an identity. If the named chat is missing, renamed, archived, or matches
more than one chat, the result goes to the main chat. The app does not announce the move; the
plugin's log records it. For a recurring job, or one that must keep working if a chat is renamed,
use the chat's id.

Computer view

The viewer is built into this plugin (dashboard/computer/), including its noVNC runtime under
dashboard/computer/vendor/novnc/. It loads only when you first tap the computer button; the app
shell and its service worker install without it. The viewer uses Hermes' own /api/display/ws
(display tickets and control leases) and the plugin's /api/plugins/hermes-mini/computer/clipboard
routes, which are limited to the person currently holding control.

Hermes Mini does not install desktop packages or run a desktop in the background. If Bot Desktop is
not set up, the button is hidden; when it is, Start Screen asks Hermes to start one.

Troubleshooting

  • The page 404s. The dashboard must be the process serving it, and the folder must be named
    hermes-mini. Check hermes plugins list and that dashboard/manifest.json is present.
  • Everything 401s or redirects to a login. That is Hermes' dashboard auth; sign in through the
    dashboard first.
  • "Not connected yet". The WebSocket to the Hermes gateway is down. Check the gateway is running;
    the app retries on its own.
  • No microphone. No STT provider is configured, or the browser cannot record. Configure STT in
    Hermes (see the Hermes docs), then reload.
  • No bell. cryptography/httpx are missing from Hermes' environment, or the browser does not
    support Push.
  • No computer button. Bot Desktop is unsupported or not installed on this host.
  • The name is Hermes. No bot title, display name or named profile exists yet. Set a bot name
    in Hermes and the app picks it up on the next load.

Verified, and not

Tested here against the real Hermes runtime: the plugin loads through Hermes' discovery and
register(ctx); the manifest passes hermes plugins doctor and hermes plugins validate; the app
routes the suite exercises; settings/identity/avatar validation; push key opt-in and endpoint gating;
dictation delegation to Hermes' provider with a mocked provider; the app-chat scoping and the
self-edit guard; scheduled-job target resolution across ids, names, archived chats and missing
chats; the browser module graph and service-worker asset list.

Phones: the app has been used and tested thoroughly on Android, installed to the home screen. It has
not been tested on an iPhone or iPad. It is built on standard web features Safari supports, but
expect rough edges there. Known differences: notifications need iOS 16.4 or later and the app added to
the Home Screen; approval notifications have no Approve/Deny buttons (iOS does not show them; answer
in the app); there is no vibration on swipes; dictation records in a different audio format (mp4)
whose transcription is untested; and Ogg/Opus audio falls back to the download card if Safari cannot
play it. Reports from iPhone users are welcome.

Not verified here, and worth trying yourself: a real desktop session through Bot Desktop, a real push
delivery to a device, a real speech-to-text transcription, a live scheduled-job delivery, and the
app's appearance in a specific browser. Those require services and credentials this project does not
ship. See
CHANGELOG.md for the honest status list.

Documentation

License

MIT for the original project code; see LICENSE. Bundled third-party code keeps its own
license — see THIRD_PARTY_NOTICES.md.

README from the reviewed commit a8e79bf; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section