{"repo":"NousResearch/hermes-agent","public_id":"40464","display_label":"Windows docs fix for hermes PATH command guidance","summary":"These items address a documentation error in windows-native.md where the Get-Command hermes path shown after installation was incorrect. The changes correct the guidance to reflect the proper venv\\Scripts\\hermes.exe location.","subsystem":"docs","counts":{"members":3,"open_issues":0,"open_issues_distinct":0,"open_prs":0,"closed_issues":1,"merged_prs":1,"attempt_prs":1},"landed_fix":{"status":"merged_to_main","basis":"structural","pr":40613,"merged_at":"2026-06-08T01:28:24+00:00"},"resolution":{"state":"resolved","by":"pr-40613"},"freshness":{"state":"verified","last_verified_at":"2026-06-08T01:28:24+00:00","is_stale":false},"grouping":{"backbone":"STRUCTURAL_SPANNING","link_density":0.6666666666666666},"fix_edges":[{"issue_number":40464,"pr_number":40613,"tier":"verified","basis":"closing_ref","confidence":0.95,"recoverable_from_timeline":true,"pr_merged_at":"2026-06-08T01:28:24+00:00"}],"members":[{"kind":"issue","number":40464,"title":"Doc: windows-native.md — Get-Command hermes path mismatch after install","url":null,"state":"closed"},{"kind":"pr","number":40488,"title":"docs(windows): fix Get-Command hermes PATH guidance","url":null,"state":"closed","close_reason":{"refs":[{"kind":"pr","value":"#40613","number":40613}],"category":"uncategorized","implication":"needs_llm"},"merged":false,"is_fix_pr":true,"fix_tier":"suggested","fix_detail_withheld":true},{"kind":"pr","number":40613,"title":"docs(windows): fix Get-Command PATH guidance to venv\\Scripts\\hermes.exe","url":null,"state":"merged","close_reason":{"category":"merged"},"merged":true,"is_fix_pr":true,"fix_tier":"verified","files_changed":["tests/hermes_cli/test_windows_native_docs.py","website/docs/user-guide/windows-native.md"],"fix_hunks":[{"file":"tests/hermes_cli/test_windows_native_docs.py","hunks":["@@ -0,0 +1,10 @@\n+from pathlib import Path\n+\n+\n+def test_windows_native_install_path_docs_match_installer() -> None:\n+    doc = Path(\"website/docs/user-guide/windows-native.md\").read_text()\n+    install = Path(\"scripts/install.ps1\").read_text()\n+\n+    assert \"%LOCALAPPDATA%\\\\hermes\\\\hermes-agent\\\\venv\\\\Scripts\" in doc\n+    assert \"Get-Command hermes        # should print C:\\\\Users\\\\<you>\\\\AppData\\\\Local\\\\hermes\\\\hermes-agent\\\\venv\\\\Scripts\\\\hermes.exe\" in doc\n+    assert '$hermesBin = \"$InstallDir\\\\venv\\\\Scripts\"' in install"]},{"file":"website/docs/user-guide/windows-native.md","hunks":["@@ -17,12 +17,10 @@ If you prefer a real POSIX environment (for the dashboard's embedded terminal, `\n \n ## Quick install\n \n-[Download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/desktop) from our website and run it.\n-\n-Or, for a command-line only install, open **PowerShell** (or Windows Terminal) and run:\n+Open **PowerShell** (or Windows Terminal) and run:\n \n ```powershell\n-iex (irm https://hermes-agent.nousresearch.com/install.ps1)\n+iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)\n ```\n \n No admin rights required. The installer goes to `%LOCALAPPDATA%\\hermes\\` and adds `hermes` to your **User PATH** — open a new terminal after it finishes.","@@ -30,32 +28,38 @@ No admin rights required. The installer goes to `%LOCALAPPDATA%\\hermes\\` and add\n **Installer options** (requires the scriptblock form to pass parameters):\n \n ```powershell\n-& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -NoVenv -SkipSetup -Branch main\n+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main\n ```\n \n-| Parameter     | Default                              | Purpose                                                    |\n-| ------------- | ------------------------------------ | ---------------------------------------------------------- |\n-| `-Branch`     | `main`                               | Clone a specific branch (useful for testing PRs)           |\n-| `-Commit`     | unset                                | Pin install to a specific commit SHA (overrides `-Branch`) |\n-| `-Tag`        | unset                                | Pin install to a specific git tag (e.g. `v0.14.0`)         |\n-| `-NoVenv`     | off                                  | Skip venv creation (advanced — you manage Python yourself) |\n-| `-SkipSetup`  | off                                  | Skip the post-install `hermes setup` wizard                |\n-| `-HermesHome` | `%LOCALAPPDATA%\\hermes`              | Override data directory                                    |\n-| `-InstallDir` | `%LOCALAPPDATA%\\hermes\\hermes-agent` | Override code location                                     |\n+| Parameter | Default | Purpose |\n+|---|---|---|\n+| `-Branch` | `main` | Clone a specific branch (useful for testing PRs) |\n+| `-Commit` | unset | Pin install to a specific commit SHA (overrides `-Branch`) |\n+| `-Tag` | unset | Pin install to a specific git tag (e.g. `v0.14.0`) |\n+| `-NoVenv` | off | Skip venv creation (advanced — you manage Python yourself) |\n+| `-SkipSetup` | off | Skip the post-install `hermes setup` wizard |\n+| `-HermesHome` | `%LOCALAPPDATA%\\hermes` | Override data directory |\n+| `-InstallDir` | `%LOCALAPPDATA%\\hermes\\hermes-agent` | Override code location |\n \n The installer auto-retries flaky git fetches and strips BOM from any downloaded `install.ps1` payload, so a UTF-8 BOM picked up during HTTP transit no longer breaks the `[scriptblock]::Create((irm ...))` form.\n \n+### Desktop installer (alternative)\n+\n+A thin GUI installer is also available — useful if you'd rather double-click an `.exe` than open PowerShell. Download Hermes Desktop, run the installer, and on first launch the GUI calls `install.ps1` under the hood to provision Python (via `uv`), Node, PortableGit, and the rest of the dependency bootstrap described below. After the first run, the desktop app and the PowerShell-installed `hermes` CLI share the same `%LOCALAPPDATA%\\hermes\\hermes-agent` install and `%USERPROFILE%\\.hermes` data directory — switch between the GUI and the CLI freely.\n+\n+Use the desktop installer when you want a familiar Windows install experience or you're handing Hermes to a non-developer; use the PowerShell one-liner when you're already in a terminal.\n+\n ### Dependency bootstrap (`dep_ensure`)\n \n On first launch (and on demand when a missing tool is detected), Hermes runs a small Python bootstrapper — `hermes_cli/dep_ensure.py` — that checks for and lazily installs the non-Python dependencies it needs. On Windows, the relevant ones are:\n \n-| Dependency       | Why Hermes needs it                                                                                                          |\n-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n-| **PortableGit**  | Provides `bash.exe` for the terminal tool and `git` for in-session clones. Provisioned at install time, not by `dep_ensure`. |\n-| **Node.js 22**   | Required for the browser tool (`agent-browser`), the TUI's web bridge, and the WhatsApp bridge.                              |\n-| **ffmpeg**       | Audio format conversion for TTS / voice messages.                                                                            |\n-| **ripgrep**      | Fast file search — falls back to `grep` if unavailable.                                                                      |\n-| **npm packages** | `agent-browser`, Playwright Chromium, and any per-toolset Node deps are installed once at first browser-tool use.            |\n+| Dependency | Why Hermes needs it |\n+|---|---|\n+| **PortableGit** | Provides `bash.exe` for the terminal tool and `git` for in-session clones. Provisioned at install time, not by `dep_ensure`. |\n+| **Node.js 22** | Required for the browser tool (`agent-browser`), the TUI's web bridge, and the WhatsApp bridge. |\n+| **ffmpeg** | Audio format conversion for TTS / voice messages. |\n+| **ripgrep** | Fast file search — falls back to `grep` if unavailable. |\n+| **npm packages** | `agent-browser`, Playwright Chromium, and any per-toolset Node deps are installed once at first browser-tool use. |\n \n Each dep has a `shutil.which(...)`-style check; if a binary is missing and the run is interactive, `dep_ensure` offers to install it (deferring to `scripts\\install.ps1 -ensure <dep>` for the actual install logic). Non-interactive runs (gateway, cron, headless desktop launches) skip the prompt and surface a clear `this feature needs <dep>` error instead.\n ","@@ -82,18 +86,18 @@ On Windows, per-tool API key setup (Firecrawl, FAL, Browser Use, OpenAI TTS) is\n \n Everything except the dashboard's embedded terminal pane runs natively on Windows.\n \n-| Feature                                                               | Native Windows      | WSL2                   |\n-| --------------------------------------------------------------------- | ------------------- | ---------------------- |\n-| CLI (`hermes chat`, `hermes setup`, `hermes gateway`, …)              | ✓                   | ✓                      |\n-| Interactive TUI (`hermes --tui`)                                      | ✓                   | ✓                      |\n-| Messaging gateway (Telegram, Discord, Slack, WhatsApp, 15+ platforms) | ✓                   | ✓                      |\n-| Cron scheduler                                                        | ✓                   | ✓                      |\n-| Browser tool (Chromium via Node)                                      | ✓                   | ✓                      |\n-| MCP servers (stdio and HTTP)                                          | ✓                   | ✓                      |\n-| Local Ollama / LM Studio / llama-server                               | ✓                   | ✓ (via WSL networking) |\n-| Web dashboard (sessions, jobs, metrics, config)                       | ✓                   | ✓                      |\n-| Dashboard `/chat` embedded terminal pane                              | ✗ (needs POSIX PTY) | ✓                      |\n-| Auto-start at login                                                   | ✓ (schtasks)        | ✓ (systemd)            |\n+| Feature | Native Windows | WSL2 |\n+|---|---|---|\n+| CLI (`hermes chat`, `hermes setup`, `hermes gateway`, …) | ✓ | ✓ |\n+| Interactive TUI (`hermes --tui`) | ✓ | ✓ |\n+| Messaging gateway (Telegram, Discord, Slack, WhatsApp, 15+ platforms) | ✓ | ✓ |\n+| Cron scheduler | ✓ | ✓ |\n+| Browser tool (Chromium via Node) | ✓ | ✓ |\n+| MCP servers (stdio and HTTP) | ✓ | ✓ |\n+| Local Ollama / LM Studio / llama-server | ✓ | ✓ (via WSL networking) |\n+| Web dashboard (sessions, jobs, metrics, config) | ✓ | ✓ |\n+| Dashboard `/chat` embedded terminal pane | ✗ (needs POSIX PTY) | ✓ |\n+| Auto-start at login | ✓ (schtasks) | ✓ (systemd) |\n \n The dashboard's `/chat` tab embeds a real terminal via a POSIX PTY (`ptyprocess`). Native Windows has no equivalent primitive; Python's `pywinpty` / Windows ConPTY would work but is a separate implementation — treat as future work. **The rest of the dashboard works natively** — only that one tab shows a \"use WSL2 for this\" banner.\n ","@@ -136,12 +140,12 @@ Hermes's Windows stdio shim now sets `EDITOR=notepad` as a default. Notepad ship\n \n **User overrides still win** (they're checked before the setdefault):\n \n-| Editor    | PowerShell command                                                                 |\n-| --------- | ---------------------------------------------------------------------------------- |\n-| VS Code   | `$env:EDITOR = \"code --wait\"`                                                      |\n+| Editor | PowerShell command |\n+|---|---|\n+| VS Code | `$env:EDITOR = \"code --wait\"` |\n | Notepad++ | `$env:EDITOR = \"'C:\\Program Files\\Notepad++\\notepad++.exe' -multiInst -nosession\"` |\n-| Neovim    | `$env:EDITOR = \"nvim\"`                                                             |\n-| Helix     | `$env:EDITOR = \"hx\"`                                                               |\n+| Neovim | `$env:EDITOR = \"nvim\"` |\n+| Helix | `$env:EDITOR = \"hx\"` |\n \n The `--wait` flag on VS Code is critical — without it the editor returns immediately and Hermes gets a blank buffer back.\n ","@@ -196,13 +200,13 @@ Services require admin rights to install and tie the gateway's lifecycle to mach\n \n ## Data layout\n \n-| Path                                  | Contents                                                            |\n-| ------------------------------------- | ------------------------------------------------------------------- |\n-| `%LOCALAPPDATA%\\hermes\\hermes-agent\\` | Git checkout + venv. Safe to `Remove-Item -Recurse` and reinstall.  |\n-| `%LOCALAPPDATA%\\hermes\\git\\`          | PortableGit (only if the installer provisioned it).                 |\n-| `%LOCALAPPDATA%\\hermes\\node\\`         | Portable Node.js (only if the installer provisioned it).            |\n-| `%LOCALAPPDATA%\\hermes\\bin\\`          | `hermes.cmd` shim, added to User PATH.                              |\n-| `%USERPROFILE%\\.hermes\\`              | Your config, auth, skills, sessions, logs. **Survives reinstalls.** |\n+| Path | Contents |\n+|---|---|\n+| `%LOCALAPPDATA%\\hermes\\hermes-agent\\` | Git checkout + venv. Safe to `Remove-Item -Recurse` and reinstall. |\n+| `%LOCALAPPDATA%\\hermes\\git\\` | PortableGit (only if the installer provisioned it). |\n+| `%LOCALAPPDATA%\\hermes\\node\\` | Portable Node.js (only if the installer provisioned it). |\n+| `%LOCALAPPDATA%\\hermes\\bin\\` | `hermes.cmd` shim, added to User PATH. |\n+| `%USERPROFILE%\\.hermes\\` | Your config, auth, skills, sessions, logs. **Survives reinstalls.** |\n \n The split is deliberate: `%LOCALAPPDATA%\\hermes` is disposable infrastructure (you can blow it away and the one-liner restores it). `%USERPROFILE%\\.hermes` is your data — config, memory, skills, session history — and is identical in shape to a Linux install. Mirror it between machines and your Hermes moves with you.\n ","@@ -220,12 +224,12 @@ The browser tool uses `agent-browser` (a Node helper) to drive Chromium. On Wind\n \n ### PATH after install\n \n-The installer adds `%LOCALAPPDATA%\\hermes\\bin` to your **User PATH** via `[Environment]::SetEnvironmentVariable`. Existing terminals don't pick this up — open a new PowerShell window (or Windows Terminal tab) after installation. Close-and-reopen, don't `$env:PATH += …` by hand unless you know what you're doing.\n+The installer adds `%LOCALAPPDATA%\\hermes\\hermes-agent\\venv\\Scripts` to your **User PATH** via `[Environment]::SetEnvironmentVariable`. Existing terminals don't pick this up — open a new PowerShell window (or Windows Terminal tab) after installation. Close-and-reopen, don't `$env:PATH += …` by hand unless you know what you're doing.\n \n Verify:\n \n ```powershell\n-Get-Command hermes        # should print C:\\Users\\<you>\\AppData\\Local\\hermes\\bin\\hermes.cmd\n+Get-Command hermes        # should print C:\\Users\\<you>\\AppData\\Local\\hermes\\hermes-agent\\venv\\Scripts\\hermes.exe\n hermes --version\n ```\n ","@@ -244,11 +248,11 @@ Don't put secrets in User environment variables unless you specifically want eve\n \n These only affect native Windows installs:\n \n-| Variable                      | Effect                                                                                                                                             |\n-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n-| `HERMES_GIT_BASH_PATH`        | Override bash.exe discovery. Point at any bash — full Git-for-Windows, WSL bash via symlink, MSYS2, Cygwin. The installer sets this automatically. |\n-| `HERMES_DISABLE_WINDOWS_UTF8` | Set to `1` to disable the UTF-8 stdio shim and fall back to the locale code page. Useful for bisecting an encoding bug.                            |\n-| `EDITOR` / `VISUAL`           | Your editor for `/edit` and `Ctrl-X Ctrl-E`. Hermes defaults to `notepad` if both are unset.                                                       |\n+| Variable | Effect |\n+|---|---|\n+| `HERMES_GIT_BASH_PATH` | Override bash.exe discovery. Point at any bash — full Git-for-Windows, WSL bash via symlink, MSYS2, Cygwin. The installer sets this automatically. |\n+| `HERMES_DISABLE_WINDOWS_UTF8` | Set to `1` to disable the UTF-8 stdio shim and fall back to the locale code page. Useful for bisecting an encoding bug. |\n+| `EDITOR` / `VISUAL` | Your editor for `/edit` and `Ctrl-X Ctrl-E`. Hermes defaults to `notepad` if both are unset. |\n \n ## Uninstall\n ","@@ -283,7 +287,7 @@ Consequence: any codepath that said \"check if this PID is alive\" via `os.kill(pi\n ## Common pitfalls\n \n **`hermes: command not found` right after install.**\n-Open a new PowerShell window. The installer added `%LOCALAPPDATA%\\hermes\\bin` to User PATH, but existing shells need to be restarted to pick it up.\n+Open a new PowerShell window. The installer added `%LOCALAPPDATA%\\hermes\\bin` to User PATH, but existing shells need to be restarted to pick it up. In the meantime you can run `& \"$env:LOCALAPPDATA\\hermes\\bin\\hermes.cmd\"`.\n \n **`WinError 193: %1 is not a valid Win32 application` when running a tool.**\n You hit a shebang-script invocation that bypassed the `.cmd` shim. Hermes resolves commands through `shutil.which(cmd, path=local_bin)` so PATHEXT picks up `.CMD` — if you're invoking the tool via a hardcoded path instead, switch to the `.cmd` variant (e.g., `npx.cmd`, not `npx`).\n"]}]}],"trust":{"default_tier":"verified","includes_suggested":false}}