Skip to main content
Most Herm problems fall into one of a few categories: display rendering quirks that are artifacts of the terminal environment, gateway startup failures caused by a misconfigured Hermes home, or session state that has drifted out of sync. The sections below walk you through diagnosing and fixing each class of issue.
Tmux’s default terminal type does not advertise 256-color or true-color support, which causes Herm’s theme colors to render incorrectly — typically as washed-out or incorrect palette entries.
1

Open your tmux configuration file

Edit ~/.tmux.conf in your preferred editor. Create the file if it does not already exist.
2

Add the correct default-terminal setting

set -g default-terminal "tmux-256color"
3

Reload tmux configuration

Inside a running tmux session, press your prefix key then :, and run:
source-file ~/.tmux.conf
Or start a fresh tmux session for the change to take full effect.
4

Restart Herm

Close and reopen Herm. Colors should now render correctly.
If colors still look off after the tmux fix, try pressing Ctrl+L inside Herm to force a full terminal repaint.
Some Herm themes use colors that clash with dark terminal backgrounds, making text difficult to read — especially in low-contrast environments.Switch to a light-mode theme designed for readability in dark terminals:
/theme
This opens the interactive theme picker. Themes that work well in dark terminals include daylight, mercury, github, and warm-lightmode. Navigate the list with arrow keys and press Enter to apply a theme. The selection is saved immediately.
You can also type part of a theme name in the picker to filter the list. If you want to apply a theme without opening the picker, type /theme daylight (or any theme name) directly in the composer.
Herm renders inline images in the chat transcript using chafa, which converts images to terminal-compatible character art. If images appear as blank space or a placeholder, chafa is likely missing or not on your PATH.
1

Verify chafa is installed

which chafa
chafa --version
If the command is not found, install chafa using your system package manager. For example:
# macOS (Homebrew)
brew install chafa

# Debian / Ubuntu
sudo apt install chafa

# Fedora
sudo dnf install chafa
2

Confirm chafa is on your PATH

The shell that launches Herm must be able to find chafa. If you installed chafa in a non-standard location, add it to PATH before running Herm.
3

Restart Herm

Quit and relaunch Herm. Image rendering should now work for any inline image the agent produces.
chafa is an optional dependency. Herm works without it — images simply will not render inline if chafa is absent.
Herm spawns the Hermes Agent gateway as a subprocess at startup. If the gateway fails to start, you will see an error on launch or the chat will remain in a perpetual loading state. Run /logs inside Herm (if the UI is visible) to see the gateway’s stderr output.Common causes and fixes:Hermes home not foundHerm looks for your Hermes installation at ~/.hermes by default. If yours lives elsewhere, set the environment variable:
export HERMES_HOME=/path/to/your/hermes-home
Non-standard hermes-agent source layoutBy default, Herm expects the hermes-agent source tree at $HERMES_HOME/hermes-agent — the location used by Homebrew and hermes update. If you have a development clone or a non-standard layout, override it:
export HERMES_AGENT_ROOT=/path/to/hermes-agent
Python interpreter not foundHerm tries to locate a Python interpreter in this order: $VIRTUAL_ENV, <root>/venv, <root>/.venv, then python3. If none of these resolve correctly (common on Windows or in unusual venv setups), specify the interpreter explicitly:
export HERMES_PYTHON=/usr/bin/python3
1

Set the relevant environment variables

Add the appropriate exports above to your shell profile (e.g. ~/.zshrc or ~/.bashrc) and reload your shell.
2

Check gateway output

Run /logs inside Herm to inspect the gateway’s stderr ring buffer for specific error messages.
3

Verify your installation with /status

Type /status in the chat composer. The dialog shows the current Herm version, model, and resolved paths — confirming what Herm actually sees at runtime.
Herm does not guarantee backward compatibility with older Hermes Agent versions. If you recently updated Hermes and the gateway stopped working, check the Herm CHANGELOG for a matching update.
If Herm is showing outdated config values, MCP servers are not reflecting recent changes, or skills do not match what you see on disk, you can reload the relevant subsystem without restarting Herm.
What’s staleCommand
API keys or environment variables/reload
MCP servers/reload-mcp
Skills/reload-skills
Type the appropriate slash command in the chat composer and press Enter. Herm will call the corresponding gateway RPC and show a confirmation toast when the reload completes.
/reload hot-reloads ~/.hermes/.env via the reload.env RPC. If you have updated API keys in your environment file, /reload is the fastest way to pick them up without a full restart.
Occasional display corruption can occur when the terminal’s internal buffer gets out of sync with what Herm has rendered — for example, after resizing the terminal window, switching tmux panes rapidly, or returning from a suspended process.Press Ctrl+L at any time to force a full terminal repaint. Herm clears its baseline buffer and redraws the entire UI from scratch.
Ctrl+L works at any time — even mid-stream while the agent is responding. It does not interrupt the session.
While the agent is streaming a response, the composer is in a read-only state and normal key presses are queued rather than sent immediately. To cancel the active agent turn:Double-tap Esc — press Esc twice in quick succession.Herm will send an interrupt signal to the gateway, purge any buffered streaming deltas, and return to the ready state so you can type a new message.
A single Esc press will not interrupt a running agent — it only navigates focus within the UI. You must tap Esc twice.
On non-Chat tabs, keyboard input routes to the tab’s content pane rather than the chat composer. If you have navigated to a sidebar tab and want to get back to the composer to type a message:Double-tap Tab to jump focus directly back to the chat composer, regardless of which tab is active.A single Tab press cycles focus between the content regions of the current tab. The double-tap shortcut is a fast path back to the composer from anywhere in the UI.
If you have updated API keys in ~/.hermes/.env (or your custom HERMES_HOME path) and Herm is still using old credentials, the gateway has not yet reloaded the environment file.Type /reload in the chat composer and press Enter. Herm calls the reload.env gateway RPC, which re-reads the .env file without restarting the gateway process. You should see a confirmation toast when the reload succeeds.
1

Update your .env file

Edit ~/.hermes/.env (or $HERMES_HOME/.env) and save your updated API keys.
2

Run /reload in Herm

In the chat composer, type:
/reload
and press Enter.
3

Verify with /status

Use /status to confirm that Herm reports the correct model and paths, indicating the gateway is operating with the updated configuration.
On Windows, the Eikon tab could crash when Herm was unable to locate the correct Python virtual environment for the gateway subprocess — particularly in environments where venv paths use Windows-style separators or the Python executable name differs.
1

Update to Herm v1.8.1 or later

This crash was fixed in v1.8.1, which added cross-platform compatibility for Python venv path resolution, a Windows python executable fallback, and error handling to prevent unhandled rejections from killing the app.
bun add -g herm-tui   # updates to latest stable
npm i -g herm-tui     # or via npm
2

If the issue persists, set HERMES_PYTHON

Specify the full path to your Python interpreter explicitly:
# In your environment or a .env file
HERMES_PYTHON=C:\Python311\python.exe
You can also add this to a .env file in your Hermes home directory.
All available environment overrides are documented in .env.example in the Herm repository. All variables are optional — Herm runs without any of them when the defaults resolve correctly.