hermes-desktop

Hermes Desktop Updated

A Windows-native AI agent that lives on your desktop. Chat with it, give it tools, let it learn who you are. Built with WinUI 3 and .NET 10.

v2.5.9 — Download | Changelog | Discussion

---

Get Started

Download and run — no installer, no SDK, no setup wizard.

1. Grab HermesDesktop-portable-x64.zip from Releases
2. Extract anywhere
3. Run HermesDesktop.exe
4. Add your API key to %LOCALAPPDATA%\hermes\config.yaml

Works on Windows 10 (1809+) and Windows 11. The portable build is fully self-contained — everything ships in the folder.

model:
  provider: anthropic
  default: claude-sonnet-4-6
  base_url: https://api.anthropic.com
  api_key: sk-ant-your-key-here

# Add more providers for runtime swapping (optional)
provider_keys:
  anthropic: sk-ant-your-key
  openai: sk-proj-your-key
  ollama_url: http://127.0.0.1:11434/v1

First launch creates %LOCALAPPDATA%\hermes with config, memory, transcripts, and logs.

Updating

Portable (zip from Releases) — your data lives outside the app folder.

1. Quit Hermes Desktop (system tray → Exit, or close the window).
2. Download the latest HermesDesktop-portable-x64.zip.
3. Either replace the folder (delete the old extracted folder, extract the new zip to the same path) or extract to a new folder and run HermesDesktop.exe from there — either way, do not delete %LOCALAPPDATA%\hermes; your config.yaml, sessions, memory, and wiki stay there.
4. Start the new HermesDesktop.exe.

There is no in-app auto-updater yet; check Releases when you want a new build.

Built from git (dev / dotnet run) — pull and run again:

cd Hermes-Desktop
git pull
dotnet run --project Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64 --launch-profile "HermesDesktop (Dev)"

MSIX (run-dev.ps1) — pull, then re-register:

cd Hermes-Desktop
git pull
powershell -ExecutionPolicy Bypass -File .\Desktop\HermesDesktop\run-dev.ps1

---

What It Does

Hermes Desktop is an in-process agent runtime with a native Windows UI — not a chat wrapper. The agent runs locally, calls tools, remembers context across sessions, and can reach out to Telegram and Discord on your behalf.

Agent Runtime

• 27+ tools — file ops, shell, web fetch/search, code sandbox, browser automation, vision, TTS, and more
• Parallel execution for read-only tools (8-worker semaphore), sequential with permission gating for mutations
• Runtime model swapping — switch between Claude, GPT, Ollama, Qwen, DeepSeek, and others mid-conversation without restarting
• Sub-agent spawning with 5 profiles for delegation and parallel work
• 94 skills across 28 categories (code review, TDD, GitHub workflows, MLOps, research, creative, and more)

Memory & Identity

• Soul system — persistent personality (SOUL.md), user profile (USER.md), project rules (AGENTS.md), mistakes journal, habits journal
• 12 soul templates — Default, Creative, Teacher, Researcher, Pair Programmer, DevOps, Security, and more
• Wiki knowledge base — markdown files with SQLite FTS5 full-text search, Obsidian-compatible, crash-safe writes
• Compiled memory stack — wiki content injected into agent context automatically, configurable in config.yaml
• 6-layer context runtime — soul context, system prompt, session state, retrieved knowledge, recent turns, current message

Production Hardening

Built from lessons across 168+ upstream PRs and 46+ production incidents:

• Streaming watchdog surfaces stalled providers within 30 seconds instead of leaving chat hung
• Structured provider error codes for timeouts, auth failures, rate limits, transport failures, and malformed stream chunks
• Chat error banner with Retry and Switch Model actions when streaming fails
• MCP host bootstrap loads mcp.json at startup and registers discovered MCP tools beside native tools
• Compression cooldown (600s) to prevent infinite token-burning loops
• Provider fallback with automatic 5-minute restoration
• Credential pool rotation on 401/429
• Atomic writes (WriteThrough + FlushAsync) for crash safety
• Secret scanning on all tool outputs
• Deterministic tool-call IDs for prompt cache efficiency

Desktop App

Eight pages: Dashboard (usage insights, KPIs, platform badges), Chat (tool calling, reasoning display, model switcher, side panels), Agent (identity editor, souls browser), Skills (searchable library with categories), Memory (browser + project rules editor), Buddy (craftable vector companion with persistent visual traits), Integrations (Telegram, Discord, and more), Settings (model, memory, display, execution, paths).

Buddy Companion

• Vector avatar instead of ASCII: the Buddy page and side panel now use a native WinUI character renderer.
• Craft before hatch: choose species, palette, eyes, and accessory with a live preview before creating the companion.
• Tune without rerolling: after hatch, visual choices can be changed without changing rarity, stats, identity, name, or personality.
• Persistent and offline-safe: crafted traits save to buddy.json; the renderer is local, so no web image API is needed.

Messaging

Native C# adapters for Telegram and Discord — no Python CLI required. Slack, WhatsApp, Matrix, and webhooks are configured in the same config.yaml from Integrations; use the optional Python gateway when you want those bots live (not required just to save tokens).

---

Build from Source

For contributors or anyone who wants to hack on the code.

Requirements: Windows 10+, .NET 10 SDK, Windows App SDK 1.7

Dev mode (recommended)

git clone https://github.com/RedWoodOG/Hermes-Desktop.git
cd Hermes-Desktop
dotnet run --project Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64 --launch-profile "HermesDesktop (Dev)"

Runs unpackaged with no MSIX registration. The Dev profile enables HERMES_DESKTOP_SHOW_LOCAL_DETAILS so paths and endpoints are visible in the UI. In Visual Studio or Cursor, select the HermesDesktop (Dev) launch profile and press F5.

Packaged dev loop

powershell -ExecutionPolicy Bypass -File .\Desktop\HermesDesktop\run-dev.ps1

Builds, registers the MSIX package, and launches. Use -ShowLocalDetails to surface paths in the UI.

Build a portable zip

.\scripts\publish-portable.ps1 -Zip

Produces Desktop\HermesDesktop\bin\HermesDesktop-portable-x64.zip — self-contained, ready to distribute. For ARM64: add -Platform ARM64.

Updating from git is covered above under Updating (portable zip vs dotnet run vs run-dev.ps1).

Clean uninstall (MSIX):

Get-AppxPackage *EDC29F63* | Remove-AppxPackage
Remove-Item -Recurse -Force Desktop\HermesDesktop\bin, Desktop\HermesDesktop\obj, src\bin, src\obj -ErrorAction SilentlyContinue

To also remove user data: Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"

Manual build (if scripts don't work):

dotnet build Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64
cd Desktop\HermesDesktop\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64
Add-AppxPackage -Register AppxManifest.xml
Start-Process "shell:AppsFolder\EDC29F63-281C-4D34-8723-155C8122DEA2_1z32rh13vfry6!App"

Troubleshooting:

• App window doesn't appear? Remove old packages (Get-AppxPackage *EDC29F63* | Remove-AppxPackage), clean bin/ and obj/, rebuild.
• Check crash logs: %LOCALAPPDATA%\hermes\hermes-cs\logs\desktop-startup.log
• Check Windows crash reports: C:\ProgramData\Microsoft\Windows\WER\ReportArchive
• Close overlay software (MSI Afterburner, RTSS) — these can interfere with WinUI startup.
• Verify SDK: dotnet --version should show 10.x.x
• Build errors on BriefService or DashboardPage? See issue #25.
• Use -p:Platform=x64, not AMD64 — see Desktop/HermesDesktop/AGENTS.md for details.

MSIX signing: Local cert material (Desktop/HermesDesktop/packaging/dev-msix.pfx) must stay out of git. Generate a dev cert with scripts/new-msix-dev-cert.ps1.

---

Project Structure

Hermes-Desktop/
├── src/                         # Core agent library (Hermes.Core)
│   ├── Core/                    #   Agent loop, models, tool interfaces
│   ├── Tools/                   #   27+ tool implementations
│   ├── LLM/                     #   Provider abstraction, model swapping
│   ├── soul/                    #   Identity system, templates, profiles
│   ├── wiki/                    #   WikiManager, FTS5 search
│   ├── Context/                 #   Prompt builder, token budget
│   ├── dreamer/                 #   Background free-association worker
│   ├── gateway/                 #   Telegram, Discord adapters
│   └── ...                      #   memory, skills, security, plugins, etc.
├── Desktop/HermesDesktop/       # WinUI 3 desktop application
│   ├── Views/                   #   8 pages + side panels
│   ├── Services/                #   Chat bridge, environment, diagnostics
│   └── Strings/                 #   Localization (en-us, zh-cn)
├── skills/                      # 94 skill definitions
├── scripts/                     # Build, publish, install scripts
└── HermesDesktop.slnx

Tech Stack

.NET 10 / C# 13 • WinUI 3 (Windows App SDK 1.7, Mica backdrop) • SQLite FTS5 • Playwright • System.Text.Json

Changelog

Version	Date	Highlights
v2.5.9	2026-05-30	Release hardening and wiring verification: refreshed the Chat welcome block for Hermes Desktop, completed the Chat/Skills wiring map, wired chat Stop state and panel automation names, verified Sessions clear/delete/new-session flows, fixed Skills Hub install resolution for raw SKILL.md, GitHub blob URLs, and repo paths, preserved installed-skill frontmatter metadata, and added focused SkillsHub coverage. Release hygiene: audited release-facing files for local user paths/session leftovers, removed a machine-specific session-title fixture from tests, aligned alternate MSIX publisher metadata with the repo package publisher, and updated README/winget/release notes. Verification: CodeGraph index current, scripts/code-quality.ps1 passed with 750 tests, and the WinUI app was launched and verified with a real streamed response. Assembly / MSIX manifest 2.5.9.0.