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
Download and run — no installer, no SDK, no setup wizard.
- Grab
HermesDesktop-portable-x64.zipfrom Releases - Extract anywhere
- Run
HermesDesktop.exe - 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.
Minimal config.yaml to get chatting
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/v1First launch creates %LOCALAPPDATA%\hermes with config, memory, transcripts, and logs.
Portable (zip from Releases) — your data lives outside the app folder.
- Quit Hermes Desktop (system tray → Exit, or close the window).
- Download the latest
HermesDesktop-portable-x64.zip. - 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.exefrom there — either way, do not delete%LOCALAPPDATA%\hermes; yourconfig.yaml, sessions, memory, and wiki stay there. - 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.ps1Hermes 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.
 |
 |
 |
 |
 |
 |
 |
 |
- 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)
- 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
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.jsonat 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
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).
- 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.
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).
For contributors or anyone who wants to hack on the code.
Requirements: Windows 10+, .NET 10 SDK, Windows App SDK 1.7
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.
powershell -ExecutionPolicy Bypass -File .\Desktop\HermesDesktop\run-dev.ps1Builds, registers the MSIX package, and launches. Use -ShowLocalDetails to surface paths in the UI.
.\scripts\publish-portable.ps1 -ZipProduces Desktop\HermesDesktop\bin\HermesDesktop-portable-x64.zip — self-contained, ready to distribute. For ARM64: add -Platform ARM64.
Clean uninstall, manual build, troubleshooting
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 SilentlyContinueTo 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), cleanbin/andobj/, 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 --versionshould show10.x.x - Build errors on
BriefServiceorDashboardPage? See issue #25. - Use
-p:Platform=x64, notAMD64— seeDesktop/HermesDesktop/AGENTS.mdfor 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.
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
.NET 10 / C# 13 • WinUI 3 (Windows App SDK 1.7, Mica backdrop) • SQLite FTS5 • Playwright • System.Text.Json
| 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. |
| v2.5.8 | 2026-05-14 | Bundle E port from Electron (Tier-1 desktop UX): streaming Tool/Usage event primitives, slash command palette (10 local + 5 agent-bound, en/zh), token-usage chat footer wired to InsightsService, Winget submission flow (Directory.Build.props identity + template manifests + Generate-WingetManifests.ps1 + CI generate_winget job + winget-install self-detection in UpdateService), MemoryPage CRUD bound to MemoryManager, Skills toggle persistence + SkillsHub install UI + quarantine surface, SavedModelProfile/SavedModelStore registry with set-active in Settings, WelcomePage/SetupPage first-run wizard routed via SoulService.IsFirstRun. Builds on v2.5.6's reference-runtime backend (planning tool, command registry, streaming accumulator, durable timeline). Pre-E branch wrap: MCP host page + remote endpoint validator, Diagnostics page + report builder, in-app portable update banner with SHA-256 verification, publish-portable.ps1 emits .sha256 manifests. MIT attribution to fathah/hermes-desktop for the Electron source concepts that inspired the port. Assembly / MSIX manifest 2.5.8.0. |
| v2.5.7 | 2026-05-09 | Buddy companion redesign: replaced the ASCII Buddy page and side panel with a local WinUI vector avatar, added live character crafting for species, palette, eyes, and accessory, persisted crafted visual traits without rerolling stats, and documented the open-source art research behind the direction. Tests: Buddy crafting persistence coverage added. Assembly / MSIX manifest 2.5.7.0. |
| v2.5.6 | 2026-05-09 | Reference-runtime improvements: planning tool, command registry, streaming accumulator, structured runtime events, browser state reporting, large output routing with secret redaction, post-edit diagnostics, and durable timeline/tool lifecycle records. MCP: mcp.json now accepts standard camelCase mcpServers keys via case-insensitive config deserialization. Tests: timeline, planning, browser state, MCP casing, diagnostics, command registry, and large-output regression coverage. Assembly / MSIX manifest 2.5.6.0. |
| v2.5.5 | 2026-05-06 | Stream resilience (issue #51): mid-SSE HttpRequestException now retries against the configured fallback provider, gated to the SSE-handshake case (zero tokens emitted) and to turns currently on the primary client — avoids prompt-replay duplication and the "already on fallback" rethrow. Chat input: placeholder text now states the actual binding (Enter to send, Shift+Enter for a new line); the wrong-key resource lying about Ctrl+Enter is gone. CI: test-symbol guardrail allowlist extended with common BCL exception types so future tests don't trip on HttpRequestException/NotImplementedException/Argument*/Timeout. Assembly / MSIX manifest 2.5.5.0. |
| v2.5.4 | 2026-04-28 | Soul system repair: runtime soul label now reflects SOUL.md, reset uses the shipped Default soul, project AGENTS.md rules enter prompt context, saved agents retain provider/model, and AutoDream starts soul learning. Assembly / MSIX manifest 2.5.4.0. |
| v2.5.3 | 2026-04-28 | Brand refresh: app package icons, splash/tile assets, README logo, and Dashboard version display updated for the new Hermes mark. Assembly / MSIX manifest 2.5.3.0. |
| v2.5.2 | 2026-04-28 | Windows Sandbox: native Windows Sandbox backend using generated .wsb configs, Desktop execution backend picker option, Bash tool honors configured backend, clear setup message when Windows Sandbox is unavailable. Assembly / MSIX manifest 2.5.2.0. |
| v2.5.1 | 2026-04-27 | MCP host: startup bootstrap for mcp.json, standard config search paths, MCP tools registered with Agent and shared tool registry, native MCP input schemas exposed to models, docs at docs/mcp.md. Assembly / MSIX manifest 2.5.1.0. |
| v2.5.0 | 2026-04-27 | Reliability: 30s streaming watchdog, structured provider errors (ProviderTimeout, ProviderAuth, RateLimit, StreamParseError), OpenAI/Anthropic transport + parse error surfacing. Chat UX: visible error banner with Retry and Switch Model actions. Tests: stream watchdog regression plus full desktop test suite. Assembly / MSIX manifest 2.5.0.0. |
| v2.4.0 | 2026-04-19 | Buddy: persist to buddy/buddy.json, species hatch UI, LLM-off fallback soul, aligned panel identity. Integrations: native Telegram/Discord adapter status fix, clearer optional-Python messaging. Tests: BuddyServiceTests. Assembly / MSIX manifest 2.4.0.0. |
| v2.3.1 | 2026-04-13 | Fix v2.3.0 source zip DreamerStatusSnapshot.LastLocalDigestHint compile error, fix portable startup XamlParseException on ReplayPanel (disable PublishTrimmed), add ReplayPanel constructor diagnostic capture, refresh readme screenshots |
| v2.3.0 | 2026-04-12 | Portable release (self-contained zip, no MSIX required), compiled memory stack, wiki tool, Dev launch profile, publish-portable.ps1 |
| v2.2.1 | 2026-04-10 | Fix startup crash on fresh clone, safe file ops, one-click installer |
| v2.2.0 | 2026-04-10 | User Profile section in Settings |
| v2.1.0 | 2026-04-10 | Native C# gateway — Telegram and Discord without Python CLI |
| v2.0.0 | 2026-04-09 | Runtime model swapping (Claude/OpenAI/Ollama/Qwen mid-conversation) |
| v1.9.0 | 2026-04-09 | Wiki knowledge base with SQLite FTS5 search |
| v1.8.0 | 2026-04-09 | Production hardening: cooldowns, fallback, atomic writes, secret scanning |
| v1.7.0 | 2026-04-09 | Anthropic tool calling |
| v1.5.0 | 2026-04-08 | Parallel tool execution (8 workers) |
Earlier releases
| Version | Date | Highlights |
|---|---|---|
| v2.1.1 | 2026-04-10 | Fix skills discovery, model dropdown, memory paths |
| v2.0.1 | 2026-04-09 | Fix dark theme, first-run skill copy, gateway notice |
| v1.9.1 | 2026-04-09 | Agent tool loop tests (207 pass), Chat UX |
| v1.6.0 | 2026-04-09 | Execution backends, plugins, analytics dashboard |
| v1.4.0 | 2026-04-08 | +7 new tools (21 total) |
| v1.3.0 | 2026-04-08 | Chat routes through full Agent pipeline |
| v1.2.0 | 2026-04-08 | Settings page overhaul |
| v1.1.0 | 2026-04-08 | Skills page redesign |
Built on the NousResearch Hermes Agent architecture. This project exists to show appreciation for the NousResearch team — please support them and use the product they created.
Several Tier-1 and Tier-2 surfaces (streaming chat primitives, slash command palette, token-usage footer, Winget release flow, MemoryPage editor, skills install/toggle UI, saved-model registry, Welcome/Setup wizard) were inspired by the MIT-licensed Electron/React Hermes Desktop at https://github.com/fathah/hermes-desktop. We ported concepts and UX, not source. Full attribution lives in docs/credits.md.
MIT