> ## Documentation Index
> Fetch the complete documentation index at: https://herm.liftaris.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Herm problems and fixes

> Diagnose common Herm problems with terminal colors, inline images, gateway startup, stale config, interrupts, focus, API keys, and Windows Python setup.

Use this page when Herm starts but something looks wrong, feels stale, or cannot reach Hermes Agent.

## Quick symptom table

| Symptom                     | Likely cause                             | First fix                                         |
| --------------------------- | ---------------------------------------- | ------------------------------------------------- |
| Colors look wrong in tmux   | tmux terminal type lacks color support   | Set `tmux-256color`                               |
| Images do not render inline | `chafa` missing or not on `PATH`         | Install `chafa`                                   |
| Gateway will not start      | wrong Hermes home, agent root, or Python | Check `/logs` and `/status`                       |
| Config or skills look stale | gateway has not reloaded files           | Run `/reload`, `/reload-mcp`, or `/reload-skills` |
| Display is garbled          | terminal buffer drift                    | Press `Ctrl+L`                                    |
| Agent will not interrupt    | one `Esc` only moves focus               | Double-tap `Esc`                                  |
| Composer lost focus         | another tab owns key input               | Double-tap `Tab`                                  |

## Display

<AccordionGroup>
  <Accordion title="Colors look wrong in tmux">
    Add a true-color terminal type to `~/.tmux.conf`:

    ```bash theme={null}
    set -g default-terminal "tmux-256color"
    ```

    Reload tmux with:

    ```bash theme={null}
    tmux source-file ~/.tmux.conf
    ```

    Restart Herm after changing tmux configuration.
  </Accordion>

  <Accordion title="Text is hard to read">
    Open `/theme` and choose a light or high-contrast theme such as `daylight`, `mercury`, `github`, or `warm-lightmode`.
  </Accordion>

  <Accordion title="Display looks garbled">
    Press `Ctrl+L`. Herm clears its render baseline and repaints the full UI. This does not interrupt the active session.
  </Accordion>
</AccordionGroup>

## Images and eikons

<AccordionGroup>
  <Accordion title="Inline images are not displaying">
    Herm renders inline images through [`chafa`](https://hpjansson.org/chafa/). Check whether it is installed:

    ```bash theme={null}
    which chafa
    chafa --version
    ```

    Install it with your package manager:

    ```bash theme={null}
    brew install chafa       # macOS
    sudo apt install chafa   # Debian or Ubuntu
    sudo dnf install chafa   # Fedora
    ```

    chafa is optional. Herm still works without inline image rendering.
  </Accordion>

  <Accordion title="Eikon rendering fails">
    Eikon Studio media decoding needs `ffmpeg`. The `native` rasterizer avoids `chafa`, but it still depends on `ffmpeg` for media decoding.

    Install `ffmpeg`, restart Herm, then reopen Studio.
  </Accordion>
</AccordionGroup>

## Gateway startup

<AccordionGroup>
  <Accordion title="Gateway will not start or Herm cannot find Hermes">
    Herm starts the Hermes Agent gateway as a subprocess. If startup fails, run `/logs` when the UI is visible.

    Common overrides:

    ```bash theme={null}
    export HERMES_HOME=/path/to/hermes-home
    export HERMES_AGENT_ROOT=/path/to/hermes-agent
    export HERMES_PYTHON=/usr/bin/python3
    ```

    Use `/status` to confirm the resolved Herm version, gateway model, and paths.
  </Accordion>

  <Accordion title="API keys are not picked up after editing .env">
    Run `/reload` after editing `~/.hermes/.env` or the active profile `.env` file.

    ```text theme={null}
    /reload
    ```
  </Accordion>

  <Accordion title="MCP servers or skills look stale">
    Use the reload command for the stale surface.

    | Surface                           | Command          |
    | --------------------------------- | ---------------- |
    | API keys or environment variables | `/reload`        |
    | MCP servers                       | `/reload-mcp`    |
    | Skills                            | `/reload-skills` |
  </Accordion>
</AccordionGroup>

## Session control

<AccordionGroup>
  <Accordion title="Cannot interrupt a running agent">
    Double-tap `Esc`. A single `Esc` press only moves focus or shows an interrupt notice. The second press sends the interrupt.
  </Accordion>

  <Accordion title="Composer loses focus">
    Double-tap `Tab` to return focus to the composer from any non-Chat tab. A single `Tab` cycles focus within the current tab.
  </Accordion>

  <Accordion title="Session state seems stale">
    Press `r` in session lists to refresh visible rows. Use `/reload` only for environment changes and `/reload-mcp` only for MCP/tool changes.
  </Accordion>
</AccordionGroup>

## Windows

<AccordionGroup>
  <Accordion title="Python cannot be found on Windows">
    Set `HERMES_PYTHON` to the Python executable that has Hermes Agent dependencies available.

    ```powershell theme={null}
    $env:HERMES_PYTHON = "C:\Python311\python.exe"
    ```

    Then restart Herm.
  </Accordion>
</AccordionGroup>

## Related docs

* [Quickstart](/quickstart)
* [Configuration](/configuration)
* [FAQ](/troubleshooting/faq)