History

Teknium b14d75f8af fix(update): prevent and self-heal half-updated venvs on Windows (#57659 ) Root-causes the July 2026 Windows incident chain (locked _brotlicffi.pyd / _sodium.pyd during install, then 'No module named annotated_doc' with 'hermes update' insisting 'Already up to date!'): - hermes update: probe venv core imports even when the checkout is current; a half-updated venv (dep sync killed mid-flight by a locked .pyd) is now detected and repaired instead of being reported as up to date - hermes update (Windows): after pausing gateways, refuse to mutate the venv while other processes run from the venv interpreter (the Desktop backend runs as python.exe so the hermes.exe shim guard never saw it); --force keeps the old behavior - install.ps1 venv stage: disarm gateway autostart Scheduled Tasks before the kill sweep (they respawn the gateway inside the kill->delete window), make the sweep a bounded loop requiring 3 clean passes, and rename-then- delete the old venv (a rename succeeds even with mapped DLLs) with stale- dir cleanup on the next run - desktop updater: 'venv shim still locked after 15s' now ABORTS the update hand-off (restarting our backend, surfacing the holder to the user) instead of 'proceeding anyway (force)' into guaranteed venv corruption; the unlock wait also re-kills respawned backends each poll tick		2026-07-03 03:24:08 -07:00
..
assets	fix(desktop): pad app icon to Apple grid so dock size matches peers (#42946 )	2026-06-09 11:48:26 -05:00
electron	fix(update): prevent and self-heal half-updated venvs on Windows (#57659 )	2026-07-03 03:24:08 -07:00
pr-assets	Show messaging source folders in desktop sessions	2026-06-07 23:44:04 -07:00
public	fix(desktop): pad app icon to Apple grid so dock size matches peers (#42946 )	2026-06-09 11:48:26 -05:00
scripts	feat(desktop): Memory Graph — playable radial timeline of memories + skills	2026-06-30 00:54:21 -05:00
src	refactor(desktop): only poll the transcript when it's a messaging session	2026-07-03 04:38:45 -05:00
.prettierrc	Add Hermes desktop app (#20059 )	2026-05-31 17:46:56 -05:00
components.json	feat(desktop): add shared project UI primitives	2026-06-25 16:40:27 -05:00
DESIGN.md	docs(desktop): add DESIGN.md design-system guide + close two consistency gaps (#40823 )	2026-06-06 22:13:17 +00:00
eslint.config.mjs	change(tooling): remove react-compiler eslint, update concurrently	2026-06-10 11:59:34 -04:00
index.html	feat(desktop): composer status stack, live subagent windows, editable prompts (#44630 )	2026-06-12 08:30:06 -05:00
package.json	feat(desktop): Memory Graph — playable radial timeline of memories + skills	2026-06-30 00:54:21 -05:00
preview-demo.html	Add Hermes desktop app (#20059 )	2026-05-31 17:46:56 -05:00
README.md	fix(desktop): route old runtimes through `dashboard` when `serve` is absent	2026-06-28 22:10:42 -05:00
tsconfig.json	fix(desktop): set tsconfig lib/target to ES2023 for findLast/findLastIndex	2026-06-08 22:14:28 -07:00
vite.config.ts	feat(desktop): Memory Graph — playable radial timeline of memories + skills	2026-06-30 00:54:21 -05:00

README.md

Hermes Desktop ☤

The native desktop app for Hermes Agent — the self-improving AI agent from Nous Research. Same agent, same skills, same memory as the CLI and gateway, in a polished native window — chat with streaming tool output, side-by-side previews, a file browser, voice, and settings, no terminal required. Available for macOS, Windows, and Linux.

Chat with the full agent	Streaming responses, live tool activity, structured tool summaries, and the same conversation history as every other Hermes surface.
Side-by-side previews	Render web pages, files, and tool outputs in a right-hand pane while you keep chatting.
File browser	Explore and preview the working directory without leaving the app.
Voice	Talk to Hermes and hear it back.
Settings & onboarding	Manage providers, models, tools, and credentials from a real UI. First-run setup gets you to your first message in seconds.
Stays current	Built-in updates pull the latest agent and rebuild the app in place.

Install

Install with Hermes (recommended)

Already have the Hermes CLI? Just run:

hermes desktop

It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. On first launch Hermes walks you through picking a provider and model; nothing else to configure.

Prebuilt installers

Prebuilt installers are built and distributed via the Hermes Desktop website..

Updating

The app checks for updates in the background and offers a one-click update when one is ready. You can also update any time from the CLI:

hermes update

Requirements

The installer handles everything for you (Python 3.11+, a portable Git, ripgrep).

Development

Want to hack on the app itself? Install workspace deps from the repo root once, then run the dev server from this directory:

npm install          # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev          # Vite renderer + Electron, which boots the Python backend

Point the app at a specific source checkout, or sandbox it away from your real config:

HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # exercise the startup overlay with deterministic delays

Building installers

npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # unpacked app under release/ (no installer)

Installers are built and uploaded to GitHub Releases manually. macOS/Windows signing & notarization happen automatically when the relevant credentials are present in the environment (CSC_LINK / CSC_KEY_PASSWORD / APPLE_* for macOS, WIN_CSC_* for Windows).

How it works

The packaged app ships the Electron shell and a native React chat surface. On first launch it can install the Hermes Agent runtime into HERMES_HOME (~/.hermes, or %LOCALAPPDATA%\hermes on Windows) — the same layout a CLI install uses, so the two are interchangeable. Backend resolution first honours HERMES_DESKTOP_HERMES_ROOT, then a completed managed install, then a probed hermes on PATH (unless HERMES_DESKTOP_IGNORE_EXISTING=1 is set), and finally an explicit HERMES_DESKTOP_HERMES command override for packagers/troubleshooting. The renderer (React, in src/) talks to a headless backend the app launches for you — a hermes serve process that serves the tui_gateway JSON-RPC/WebSocket API — through the framework-agnostic client in apps/shared (the same client the web dashboard consumes), and reuses the agent runtime rather than embedding hermes --tui. The app is self-contained: it runs its own hermes serve backend and never opens or requires the web dashboard UI. (For backward compatibility, a runtime that predates the serve command automatically falls back to a headless dashboard --no-open — see electron/backend-command.cjs — so mid-upgrade installs never break.) The install, backend-resolution, and self-update logic all live in electron/main.cjs.

Verification

Run before opening a PR (lint may surface pre-existing warnings but must exit cleanly):

npm run fix
npm run typecheck
npm run lint
npm run test:desktop:all

Troubleshooting

Boot logs land in HERMES_HOME/logs/desktop.log (includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure.

macOS / Linux:

# Force a clean first-launch setup
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
# Rebuild a broken Python venv
rm -rf "$HOME/.hermes/hermes-agent/venv"
# Reset a stuck macOS microphone prompt (macOS only)
tccutil reset Microphone com.nousresearch.hermes

Windows (PowerShell):

# Force a clean first-launch setup
Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
# Rebuild a broken Python venv
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"

The default Hermes home on Windows is %LOCALAPPDATA%\hermes. Set the HERMES_HOME env var if you've relocated it.

Community

💬 Discord
📖 Documentation
🐛 Issues

License

MIT — see LICENSE.

Built by Nous Research.