Skip to main content
Whether you’re just getting started or have been running Herm in your daily workflow for a while, you’re likely to run into questions about how it fits alongside Hermes Agent, where your data lives, and how to customize the experience. The answers below cover the most commonly asked questions — from runtime compatibility to eikons and plugins.
No. Herm is a keyboard-driven terminal UI (TUI) that operates Hermes Agent — it does not replace it, implement model providers itself, or own any Hermes runtime behavior. Think of Herm as an operator dashboard: it gives you a single terminal interface for chatting with Hermes, managing sessions, inspecting context, running kanban work, and configuring your Hermes home, all without leaving the shell.Hermes Agent must be installed and running for Herm to function. Herm spawns the Hermes gateway as a subprocess and communicates with it over a stdio JSON-RPC connection.
Herm does not guarantee backward compatibility with older versions of Hermes Agent. Because Hermes is actively developed and its interfaces change frequently, things can break when Hermes updates. The Herm team runs regular Hermes parity sweeps to keep Herm current, but there is no promise that a given Herm release will work with a Hermes version older than the one it was built against.If you experience unexpected behavior after a Hermes update, check /status inside Herm to see the version information for both Herm and the gateway, then consult the changelog to find the matching Herm release.
Yes. Herm is built with Bun and Bun ≥ 1.3.0 is the recommended runtime, but a Node package runner works too. The npm global install is fully supported:
npm i -g herm-tui
If you have Bun available and want to try Herm without a permanent global install, bunx runs it directly from the registry without adding it to your global bin:
bunx herm-tui
You can also run from source by cloning the repo and using your package runner of choice.
Herm reads from and writes to your Hermes home directory, which defaults to ~/.hermes. This is where Hermes Agent stores profiles, sessions, skills, and other operational data.Herm’s own preferences and input history are stored separately in $HERMES_HOME/herm by default. You can relocate this directory by setting HERM_CONFIG_DIR in your environment.If your Hermes home lives somewhere other than ~/.hermes, set the HERMES_HOME environment variable to point Herm (and Hermes) at the right location. See .env.example for all available overrides — all of them are optional.
Use the /model slash command from the chat composer to open the model picker. Model changes are session-scoped by default, meaning the selected model applies to the current session only. To change the model globally (across all sessions), use the --global flag when prompted.You can also navigate to the Config tab and look under the Models category, which exposes the main model slot plus auxiliary task slots — the same controls available through the web UI’s model settings panel.
Yes, Windows support was added in v1.6.0. The npm launcher shim resolves correctly on Windows via a .ps1 script, so a standard npm i -g herm-tui install should work.
If the Eikon tab crashes or you see Python-related errors on Windows, set the HERMES_PYTHON environment variable to the full path of your Python interpreter. This is needed when Herm cannot automatically discover the correct Python venv — a fix for the most common Windows crash scenario was shipped in v1.8.1.
An eikon is an animated avatar displayed in the Herm sidebar during chat. The word comes from the ancient Greek eikōn (εἰκών), meaning image or likeness — and in Herm’s context, it is a sculptural identity for your Hermes session.Eikons are encoded as .eikon NDJSON files that describe braille or character-art frames, states (idle, listening, thinking, error), and playback timing. Herm ships with a built-in default eikon and supports installing additional eikons from the Marketplace or from local files.
There are two ways to install an eikon:From the Marketplace (recommended):
  1. Navigate to the Eikon tab (press Alt+5 or use /gallery).
  2. Press M from the Gallery sub-tab to open the native Eikon Marketplace.
  3. Search the catalog, preview your selection, and press the install key to install without activating.
  4. Return to Gallery to activate the newly installed eikon when you’re ready.
From a local file: Use the /eikon slash command or the command palette (Ctrl+K) to open the eikon picker and select a local .eikon file.
Herm’s native Marketplace handles all install and activation logic. The eikon.liftaris.dev site is a discovery mirror only — use it to browse and preview catalog entries, then install from within Herm itself.
A skin is a combined preset that sets a Hermes profile, a Herm color theme, and a bundled eikon in a single command. Use /skin from the chat composer to browse and apply available skins. Switching a skin is non-destructive — you can change it again at any time.
Herm exposes a plugin API built on the @opentui/react SlotRegistry. Plugins can render into named slots such as the bottom gutter and sidebar avatar, and can be wired into the Eikon Studio for live preview.The plugin system shipped in v1.6.0. Demo plugin files (files and clock) are included in the source tree but are disabled by default. To get started, examine those files in src/ for the slot API shape and the SKILL.md + preview.sh scaffold pattern used by Eikon Studio plugins.
Plugin documentation is evolving alongside the API. If you are writing a plugin against the current release, check the CHANGELOG for any breaking changes to the slot API between versions.