Skip to main content
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.
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: 
    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: 
    "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.
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: 
    hermes acp --check
    That command prints exactly which dependency is missing and what you need to install.
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.
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.
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:
"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.
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.
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.
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).

​
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 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
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 is the right starting point.