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

# Troubleshoot Hermes Agent VS Code Extension Issues

> Fix common Hermes Agent extension problems — stuck connections, missing ACP dependencies, model list issues, and language display bugs.

When something goes wrong, the first place to look is the ACP connection log. Open it by clicking **More options (…)** in the chat title bar, then selecting **Logs**. The log shows every message exchanged over the Agent Client Protocol and usually makes the root cause obvious. The sections below cover the most common scenarios and how to resolve them.

<AccordionGroup>
  <Accordion title="Stuck on 'Connecting…'">
    If the status pill stays on **Connecting…** and never turns green, Hermes is either not on your PATH or the ACP subprocess could not start.

    1. Open the **Wrench (Environment)** menu in the chat toolbar and select **Environment detection**. The extension runs a layered scan (L0–L5) and reports exactly where the problem is.
    2. Confirm that `hermes` is accessible from your terminal by running:
       ```bash theme={null}
       hermes --version
       ```
    3. If the command is not found, either install Hermes or set the `hermes.path` setting to the full path of the executable:
       ```json theme={null}
       "hermes.path": "/usr/local/bin/hermes"
       ```
    4. After updating the path, connection-related setting changes trigger an automatic reconnect — you should not need to reload manually.
  </Accordion>

  <Accordion title="'ACP dependencies missing' error">
    The extension needs the `agent-client-protocol` Python package to communicate with Hermes over ACP.

    * **Automatic fix:** Environment detection (`hermes.detectEnvironment`) runs `pip install agent-client-protocol==0.9.0` automatically when it detects the package is missing, then re-checks readiness.
    * **Manual fix:** If the auto-install fails (for example, because of a restricted network or a non-standard Python environment), run the following in a terminal yourself:
      ```bash theme={null}
      hermes acp --check
      ```
      That command prints exactly which dependency is missing and what you need to install.
  </Accordion>

  <Accordion title="Connection error / Can't connect">
    A **Connection error** banner means the ACP session failed after the initial handshake — different from being stuck before it.

    1. Click **Retry** in the chat toolbar to attempt reconnection immediately.
    2. If the error persists, open **More options → Logs** to read the raw error message.
    3. Try **Hermes: Reload Session** (`hermes.reloadSession`) to restart only the ACP session without touching the rest of the extension.
    4. If the session reload does not help, run **Hermes: Reload Extension** (`hermes.reloadExtension`) to restart the full extension process.
  </Accordion>

  <Accordion title="'Hermes is initializing…' message">
    After connecting, the first message you send may show a status of **Hermes is initializing…** for up to a few minutes. This is expected behaviour, not an error.

    * On the first prompt after a new connection, Hermes loads its plugin stack. This can take **1–3 minutes** depending on your machine and the number of tools configured.
    * If no output appears after 25 seconds, a hint in the status bar confirms that Hermes is still initializing — you do not need to do anything.
    * If the message never resolves, open **More options → Logs** to verify that the connection is still alive. A stalled log with no new entries after several minutes may indicate a crashed subprocess; use **Reload Session** to recover.
  </Accordion>

  <Accordion title="Model not listed in dropdown">
    The model dropdown is populated from the list Hermes returns over ACP. If Hermes does not expose a model selector, the dropdown falls back to your `hermes.models` setting.

    Add your preferred models to the `hermes.models` array in your VS Code settings:

    ```json theme={null}
    "hermes.models": [
      { "id": "claude-sonnet", "name": "Claude Sonnet" },
      { "id": "gpt-4o", "name": "GPT-4o" }
    ],
    "hermes.defaultModel": "claude-sonnet"
    ```

    You can open settings quickly with **Hermes: Open Settings** from the Command Palette, or via **More options → Settings** in the chat title bar.
  </Accordion>

  <Accordion title="Settings not opening in Cursor">
    In Cursor, pressing `Ctrl+,` or running **Open Settings** from the Command Palette sometimes opens `settings.json` directly or does nothing visible.

    Use the chat title bar instead:

    1. Click **More options (…)** in the chat title bar.
    2. Select **Settings**.

    This opens the VS Code Settings UI filtered to the Hermes extension regardless of whether you are in VS Code or Cursor.
  </Accordion>

  <Accordion title="UI not in the expected language">
    The extension ships with English and Simplified Chinese (简体中文) UI strings and automatically follows your VS Code display language setting.

    If you change VS Code's display language but the Hermes sidebar still shows the old language:

    1. Open a different view or panel in the activity bar.
    2. Click the **Hermes Agent** icon to switch back to the Hermes sidebar.

    Toggling away from and back to the sidebar forces the WebView to re-render with the updated locale strings.
  </Accordion>

  <Accordion title="Messages from another session appearing in the current one">
    This symptom — where streaming output from one session bleeds into a different session's chat — was a known bug fixed in **v0.3.2**.

    * **Update the extension** to v0.3.2 or later. Session updates whose `sessionId` does not match the active session are now silently ignored.
    * After updating, run **Hermes: Reload Extension** to ensure the old code is fully replaced.

    If you see this on v0.3.2+, open **More options → Logs** and capture the session IDs shown in the log, then file a bug (see below).
  </Accordion>
</AccordionGroup>

## Getting more help

If none of the steps above resolve your issue, open a bug report on GitHub:

**[github.com/acester822/FTR10-Hermes-VSCode/issues](https://github.com/acester822/FTR10-Hermes-VSCode/issues)**

To help diagnose the problem quickly, include the following in your report:

* **VS Code version** (Help → About)
* **Extension version** (should be `0.3.2` or later; check Extensions → FTR10 Hermes VSCode)
* **Hermes Agent version** — run `hermes --version` in a terminal and paste the output
* **Steps to reproduce** — what you did, what you expected, and what actually happened
* **Logs** — copy the output from **More options → Logs** in the chat title bar

<Note>
  Before filing a bug, confirm that Hermes itself works outside VS Code by running `hermes acp` in a terminal. If that command fails, the problem is with your Hermes installation rather than the extension, and the [Hermes Agent documentation](https://hermes-agent.nousresearch.com) is the right starting point.
</Note>