Diagnose Hermes CLI/TUI (Windows)

Playbook for running and fixing the Hermes Agent CLI/TUI on this machine. Use when the TUI misrenders, truncates, shows unreadable indicators, fails to launch, or when asked how to theme/skin Hermes on Windows.

Disambiguation: if the desktop app (Electron) fails to launch or shows a blank window, see diagnosing-desktop — that is a desktop-app problem, not a CLI/TUI problem. If a /command is missing or overridden, see diagnosing-commands.

0. Environment baseline (origin machine: one Windows box, re-verified 2026-09-14)

[!CAUTION] This baseline records one specific Windows machine — the box this skill was written on. It is not a description of your machine. Before applying anything below, confirm the local environment with hermes config path, hermes --version, and hermes doctor; paths, HERMES_HOME, shell, and OS differ per machine (on macOS/Linux the default home is ~/.hermes — overridable via HERMES_HOME or a named profile; hermes config path always prints the active one).

• Hermes Agent v2026.9.24 on the Windows desktop install (v0.20.4 when this skill was first written, v0.21.1 at the 2026-09-14 re-check); git install: %LOCALAPPDATA%\hermes\hermes-agent (on the box this baseline was recorded the in-tree venv was a .venv/, not venv/; a PM-era install has no in-tree venv at all — see diagnosing-path for why that matters)
• HERMES_HOME = %LOCALAPPDATA%\hermes (native Windows; ~/.hermes is NOT the active home)
• OS: Windows 10 Home 22H2 (build 19045.7663)
• Shell: Windows PowerShell 5.1; console host: conhost (classic window) or Windows Terminal 1.24.11911 (present on the reference box; a bare Windows 10 box has only conhost)
• Tool shell backend: PortableGit (MinGit, msys2) bash - resolved via HERMES_GIT_BASH_PATH or %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe (non-busybox variant)
• TUI frontend: Node app hermes-tui (React 19 + custom Ink fork), launched as a subprocess of the Python CLI. Node resolution (2026-09): through PM — hermes_cli/main_tui_launch.py::_tui_node_bin prefers an explicit HERMES_NODE binary, else PM's locked Node (26.7.0 in pm/lock.json); a system Node on PATH is deliberately not used to run Hermes's JS (hermes_cli/main_tui_launch.py::_tui_node_bin, asserted by the path-shape e2e tests). If no Node can be resolved, hermes --tui exits with a pointer to hermes --cli.
• Ground truth commands: hermes config path, hermes config show, hermes --version, hermes doctor

1. Launch and resume

hermes              # classic CLI by default; launches TUI when display.interface: tui
hermes --tui        # force TUI
hermes --tui -c     # resume latest TUI session (or HERMES_TUI_RESUME=1 / display.tui_auto_resume_recent: true)
hermes --cli        # force classic REPL for one invocation
hermes -z "prompt"  # one-shot (--oneshot): run a single prompt with tools, print the answer, exit.
                    #   Non-interactive — ideal for scripts, cron, and CI smoke-tests (e.g. verifying a
                    #   skill is discoverable AND followed: hermes -z "Use the diagnosing-path skill: which
                    #   interpreter should a script in the checkout use?"). Exits non-zero on failure.

Applied on the origin machine (config.yaml, backup: config.yaml.bak-20260824-0457):

display:
  interface: tui
  tui_status_indicator: ascii
  mouse_tracking: wheel
  details_mode: collapsed

display.tui_auto_resume_recent is false (fresh session per launch). If hermes ever opens a previous chat instead of a fresh session, check that key or HERMES_TUI_RESUME=1; resume on demand with hermes --tui -c (--resume <id> for a specific session).

User env vars: EDITOR=code --wait, HERMES_TUI_THEME=dark.

Stale update lock wedges every launch

Every hermes invocation hanging on an update is still running / finishing an interrupted source update with no update in progress means a leftover checkout lock (hermes_cli/update_lock.py::read_live_update judges it; hermes_cli/update_lock.py::describe_holder explains refusals). Read the holder record at <git common dir>/hermes-update.lock (or <install root>/.hermes-update.lock for a ZIP install with no .git) — pid, started_at, ct: creation time — then judge liveness the way upstream does: the owner counts live only while its pid runs and its recorded creation time still matches (2 s tolerance), so a dead pid is suggestive but a reused pid proves nothing. Three verdicts: live owner → wait (watch hermes logs), never touch the lock; dead owner and no surviving updater child (Get-Process shows no hermes update/python holdouts) → stale, safe to remove with human confirmation, then hermes --version must exit 0; dead owner but an updater-started process still runs → it holds the checkout (held) — wait, never delete. Deletion is the only write in this flow and stays human-confirmed. hermes guide update automates the PID-liveness verdict where the install can still launch (fully wedged installs start here by hand). Observed live 2026-10-16: timeout-killed plugin install, owner PID dead 6+ min, CLI recovered after removal. When probing liveness by hand, never use os.kill(pid, 0) on Windows — it terminates the target there (POSIX-only idiom); use Get-Process instead. POSIX reverses the rule: ps -p <pid> shows a live owner, and kill -0 <pid> exits 0 only while it runs — a probe there, never a signal. Read a nonzero exit carefully: permission-denied means the owner lives but is not yours (confirm with ps -p <pid>); only a no-such-process result means dead, and a reused pid still proves nothing either way.

2. In-TUI slash commands that fix rendering

3. Skins & themes (style system)

• Skins live at $HERMES_HOME/skins/<name>.yaml; user skins inherit missing keys from default
• Keys: colors (banner_, ui_, prompt, input_rule, response_border, session_, status_bar_bg, voice_status_bg, selection_bg, completion_menu_), spinner (waiting_faces, thinking_faces, thinking_verbs, wings), branding (agent_name, response_label, prompt_symbol, help_header...), tool_prefix, tool_emojis, banner_logo / banner_hero (Rich markup ASCII art)
• Built-in skins load from hermes_cli/skin_engine.py; unknown skins fall back to default
• Consoles with poor glyph coverage: prefer ASCII-ish faces (e.g. (>_<), (^_^), (o_o)) and box-drawing tool_prefix like |
• Save skin YAML as UTF-8 WITHOUT BOM (a BOM inside a folded YAML scalar silently breaks parsing)
• Visual editor: npx -y hermes-mod (community tool; honors HERMES_HOME)
• Light/dark detection order (upstream ui-tui/src/theme.ts, verified 2026-09-14):
  1. HERMES_TUI_LIGHT — 1/true/yes/on = light, 0/false/no/off = dark. Wins over everything.
  2. HERMES_TUI_THEME — named only: light or dark.
  3. HERMES_TUI_BACKGROUND — 3- or 6-digit hex (with or without #); luminance decides.
  4. COLORFGBG last field (XFCE / rxvt / Terminal.app profiles).
  5. TERM_PROGRAM light-default allow-list (currently Apple_Terminal). Anything undecidable stays dark. There is no OSC 11 probe — the hex env var is named HERMES_TUI_BACKGROUND so a future OSC 11 client could feed it, nothing more. Note hermes_cli/tips.py advertises HERMES_TUI_THEME=light|dark|<hex>, which the TUI code does not implement; trust the code, and set hex via HERMES_TUI_BACKGROUND.)

4. Windows-specific troubleshooting

1. Mojibake / garbled output: Hermes forces UTF-8 via hermes_cli/stdio.py::configure_windows_stdio() (sets CP_UTF8, PYTHONUTF8=1, PYTHONIOENCODING=utf-8). Do NOT set HERMES_DISABLE_WINDOWS_UTF8. If tool output from the Git Bash backend is garbled, set LANG=C.UTF-8 / LC_ALL=C.UTF-8 for that bash (msys2 reads Windows env). PS 5.1 pipes: $OutputEncoding = [Text.UTF8Encoding]::new().
2. Missing glyphs / tofu faces: conhost has no font fallback. Fixes: Windows Terminal + Cascadia Mono, or /indicator ascii.
3. Editor silent (/edit, Ctrl-X Ctrl-E): Hermes defaults EDITOR=notepad. Set EDITOR=code --wait (Cursor/VS Code shim works). Never point at an editor that returns immediately without --wait.
4. WinError 193 (%1 is not a valid Win32 application): invoking an extensionless shebang script. Always use the .cmd shim (npx.cmd, not npx).
5. Process liveness: never os.kill(pid, 0) on Windows — upstream's own comment (hermes_cli/gateway.py): "os.kill(pid, 0) hard-kills on Windows (TerminateProcess)", i.e. the probe kills the process instead of testing it. Use psutil.pid_exists() / gateway.status._pid_exists().
6. Gateway at login: hermes gateway install uses schtasks (ONLOGON, no admin), spawns via pythonw.exe with DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW.
7. Antivirus flags uv.exe: false positive; whitelist the %LOCALAPPDATA%\hermes\bin folder (hash changes each upgrade). Verify authenticity via gh attestation verify (see README).
8. Installer BOM: iex (irm ...) strips BOM; [scriptblock]::Create((irm ...)) does not.
9. Config schema drift: hermes config set flags display.mouse_tracking and display.details_mode as unrecognized - they ARE valid TUI keys (documented); values save and are read anyway. Do not delete them.
10. ConPTY mouse/selection loss (Windows Terminal): Windows Terminal uses ConPTY, which never delivers DEC mouse sequences (confirmed by MSFT maintainer Dustin Howett, microsoft/terminal#376). The TUI's AlternateScreen + mouse tracking swallows the wheel and native text selection. PR #97663 defaults hermes --tui to inline mode (primary buffer) on native Windows ConPTY — the same fallback Termux uses. Git Bash/MSYS mintty outside WT is unaffected. Workaround until merge: HERMES_TUI_INLINE=1. Opt out with HERMES_TUI_INLINE=0. WSL2-in-WT is intentionally excluded (WSL reports platform === 'linux', mouse sequences DO reach the Linux PTY). Additional risk: microsoft/terminal#19674 documents console mode corruption when mouse tracking + SetConsoleMode are combined — no confirmed workaround beyond inline mode.
11. Cursor / VS Code integrated-terminal spinner flood + prompt clip (classic CLI): In Cursor/VS Code, the classic CLI spinner (* (¬_¬) ruminating... (0.7s) 🚀 model ~63.2K/1M ...) floods scrollback — each tick persists as a new line instead of overwriting in place — and the > prompt then clips its first character at the left edge. Root cause (verified in source): KawaiiSpinner in agent/display.py overwrites with \r, but in Cursor/VS Code integrated terminals (narrow bottom panel) the overwrite does not land — the text is rendered through prompt_toolkit's renderer (FormattedTextControl under patch_stdout()), which repaints instead of overwriting in place; the ~90-col status line exceeds the narrow pane; shutil.get_terminal_size((80,24)) may over-report width (fallback to 80 cols when size detection fails) — verify the affected terminal's actual width and COLUMNS value before asserting the fallback caused the issue. Warning: terminals honoring CSI 3 J may have existing scrollback erased at startup (even inline); save needed output before launching the Node TUI. Permanent fix on this host is to leave the classic CLI: persist display.interface: tui, display.tui_status_indicator: ascii, display.details_mode: collapsed, display.mouse_tracking: wheel, plus HERMES_TUI_INLINE=1 in .env — the Node TUI width-budgets its segments and drops the tail first on tight terminals.

See references/cursor-vscode-spinner-flood.md for the full playbook (detection, measurement, escape hatch, apply, verify, rollback, provenance).

5. Known upstream issues (check state before re-reporting)

States verified 2026-10-08. closed means fixed or declined upstream — check the issue before reinstalling. A linked PR proposes a fix; check its review and release status before relying on it.

5b. Temporary workaround vs permanent fix

Label every remedy. A temporary workaround unblocks now and is worth undoing once the real fix lands; a permanent fix changes the host or the config and is worth keeping. Some permanent fixes are outside Hermes entirely — do not report those as Hermes bugs.

When a workaround is temporary, say what "done" looks like: the upstream issue to watch, or the version that carries the fix.

5c. Gateway session creation timeout

If hermes (TUI/agent) reports Error: Gateway did not answer session.create, the gateway RPC exceeded its budget. On a loaded host this is usually host pressure, not a Hermes defect. On POSIX or WSL, run the diagnosing-host-pressure probe first. If it exits 1, relieve pressure, re-run the probe, and restart the gateway only after it exits 0, then retry. If it exits 0 and Hermes still fails, the cause is Hermes-side: follow diagnosing-plugins or diagnosing-gateway. If it exits 2, read the partial output; an unavailable signal does not show a healthy host. On native Windows, the probe does not run; do not use it. Do not restart the gateway blindly. (Added 2026-11-04 from a live host finding; not an upstream source recheck.)

6. Cross-platform guardrails

• Prefer config/env fixes (work identically on POSIX); keep path logic runtime-resolved via HERMES_HOME
• Never hardcode C:\... paths in skills/plugins - use %LOCALAPPDATA%\hermes on Windows, ~/.hermes elsewhere
• Shell commands issued by the agent keep POSIX syntax (the Windows backend is Git Bash); mind MSYS2 path translation and core.autocrlf
• Skins degrade to default; unknown indicator styles fall back; when Node can't be resolved the TUI exits with a hermes --cli pointer (no silent fallback) - preserve these behaviors
• Terminal persistence (persistent_shell, TERMINAL_* env carry) means shell state survives across commands — a "clean shell" repro must start a fresh non-persistent session or the old env leaks in. Local backend: exported-variable carry follows TERMINAL_LOCAL_PERSISTENT (default true, tools/terminal_tool.py); set it false before creating the terminal environment. persistent_shell is the config key, not the local switch.
• Dashboard browser-open (hermes_cli/web_server_lifecycle.py::_maybe_open_browser) fires webbrowser.open (the macOS open helper) in a daemon thread 1s after serve, mapping 0.0.0.0/:: to 127.0.0.1 and appending ?profile= when set — open failures are swallowed, so "dashboard served but no browser, no error" means retry the printed URL manually and pass --no-open to silence it. The headless-Linux skip (no DISPLAY/WAYLAND_DISPLAY) never triggers on macOS.

Verification

hermes --version; hermes doctor      # PM-managed Node, bash, deps
hermes config get display            # confirm keys above
hermes skills list                   # this skill should appear (hub or local, enabled)
# in TUI: /indicator ascii; /skin slate; /mouse wheel; /usage; /exit

Deep-dive reference: the original investigation with screenshot forensics, redundancy analysis, and full source evidence lives at references/hermes-cli-tui-windows-investigation.md in this skill's directory.

Report

This skill diagnoses CLI/TUI issues on native Windows — rendering artifacts, themes/skins, busy indicators, mouse modes, encoding, and launch/resume. When you run the diagnostic workflow, present findings in the standard format below.

Summary

Your TUI shows unreadable tofu faces for the busy indicator because conhost has no font fallback for the default kaomoji style. Switching to ASCII indicator style fixes the readability.

Findings

Recommended Fix

Run /indicator ascii in the TUI for an immediate fix, then persist by adding display.tui_status_indicator: ascii to config.yaml. For the color issue, set COLORTERM=truecolor in your environment.

References

• $HERMES_HOME/config.yaml — the display: block
• hermes_cli/skin_engine.py — skin loading logic
• hermes_cli/stdio.py — configure_windows_stdio() UTF-8 handling

Facts re-verified 2026-10-09 against upstream source at commit f97608f178d1ffeca59860195ab7da295f7c8e5f (skin_engine.py, config_defaults.py, stdio.py, gateway.py, tui_gateway/server.py, ui-tui/src/theme.ts, ui-tui/src/app/useMainApp.ts, hermes_cli/cli_tui_mixin.py, hermes_cli/update_cmd.py, hermes_cli/doctor_platform.py, hermes_cli/active_sessions.py, hermes_cli/cli_voice_mixin.py), upstream docs (installation.md), the issue tracker (19 citations, states noted), and the live Windows 10 desktop install (v0.21.1, .venv, Windows Terminal 1.24.12741); Node resolution re-checked 2026-09-29 at 5000e2993 (TUI node resolves through PM; pm/lock.json pins Node 26.7.0). Terminal persistence verified 2026-10-15 against the installed source at 9bda154d (v0.21.7): persistent_shell → TERMINAL_PERSISTENT_SHELL mapping (gateway/run.py), config key set (hermes_cli/cli_config_load.py); local-backend carry follows TERMINAL_LOCAL_PERSISTENT (tools/terminal_tool.py). Dashboard browser-open verified 2026-10-15 against the installed source at 9bda154d: _maybe_open_browser (hermes_cli/web_server_lifecycle.py) — webbrowser.open in a daemon thread after 1s, failures swallowed, --no-open suppresses, headless-Linux skip only. Stale-lock verdicts verified 2026-10-16 against the installed source at 9bda154d (hermes_cli/update_lock.py marker/lock format, incarnation rule, held-holder wording; refusal strings in hermes_cli/venv_sync.py) plus a live wedge (dead PID 96771, lock removed, CLI recovered). POSIX liveness variant verified 2026-10-16 (ps/kill -0 probe semantics, EPERM-means-alive nuance). Cursor/VS Code spinner-flood playbook re-verified 2026-11-06 against the installed source at 9bda154d (agent/display.py imports StdoutProxy from prompt_toolkit.patch_stdout, checks for it in _is_patch_stdout_proxy(), and stops the animation for that proxy; hermes_cli/config.py warns on duplicate keys; hermes_cli/config_read_errors.py prints warning to stderr). Re-verify before reuse.