Hermes Desktop

Hermes Desktop is a native desktop application designed to manage, configure, and chat with Hermes Agent. It provides a GUI for managing the CLI-based Hermes environment, including installation, provider setup, and daily usage.

Key Capabilities:

• Guided Installation: Automates Hermes Agent installation and dependency resolution (Git, uv, Python 3.11+).
• Local & Remote Modes: Run Hermes locally on 127.0.0.1:8642 or connect to a remote Hermes API server via URL and API key.
• Multi-Provider Support: Connect to OpenRouter, Anthropic, OpenAI, Google (Gemini), xAI (Grok), Nous Portal, Qwen, MiniMax, Hugging Face, Groq, or local OpenAI-compatible endpoints (LM Studio, Ollama, vLLM, llama.cpp).
• Advanced Chat UI: Supports SSE streaming, tool progress indicators, Markdown rendering, and syntax highlighting.
• Slash Commands: Over 20 commands available (e.g., /usage, /tools, /model, /memory, /persona).
• Session & Profile Management: Full-text search (SQLite FTS5) for history and isolated environments via Profiles.
• Toolsets & Memory: Access to 14 toolsets (Web, Browser, Terminal, etc.) and integration with various memory providers (Honcho, Mem0, etc.).
• Messaging Gateways: Connect to 16 platforms including Telegram, Discord, Slack, WhatsApp, and more.
• Scheduling: A cron job builder for tasks ranging from minute-by-minute to weekly intervals.

The current hermes-desktop implementation is split between the Main process and the Renderer process.

Main Process (src/main/kanban.ts) Capabilities: Executes hermes kanban (local) or sshRunKanban (remote). It exposes: listBoards, currentBoard, switchBoard, createBoard, removeBoard, listTasks, getTask, createTask, assignTask, completeTask, blockTask, unblockTask, archiveTask, specifyTask, reclaimTask, commentTask, listClaw3dHqTasks, dispatchOnce.

Renderer Process (Kanban.tsx) Capabilities:

• Columns: triage, todo, ready, running, blocked, done.
• Polling: Updates every 6 seconds.
• Features: Board switcher, Claw3D HQ virtual board (read-only), create-task/create-board modals, and a read-only detail modal.
• Card Actions: specify, mark-done, reclaim, unblock, block, archive.
• Drag-drop transitions: →done, →blocked (from todo/ready/running), and blocked→ready.

Hermes Desktop provides several specialized screens for managing agentic workflows:

• Chat: Streaming conversation UI with support for slash commands, tool progress, and token tracking.
• Sessions: Browse, search, and resume past conversations.
• Agents: Create, delete, and switch between Hermes profiles.
• Skills: View, install, and manage bundled or installed skills.
• Models: Manage model settings saved per provider.
• Memory: View/edit memory entries and user profiles; configure memory providers.
• Soul: Edit the active profile's persona via SOUL.md.
• Tools: Enable or disable individual toolsets.
• Schedules: Create and manage cron jobs with specified delivery destinations.
• Gateway: Configure and control messaging platform integrations.
• Office: Set up and manage the Claw3d visual interface.
• Settings: Manage provider settings, credential pools, backups/imports, log viewer, network, and themes.

To prevent tool-call metadata or intermediate reasoning from clobbering the final user-facing text, the desktop performs a reconciliation step on message.complete.

Reconciliation Logic

The system compares the text streamed via message.delta with the final_response using mergeStreamedWithFinal. It uses the following rules:

1. Containment: If the final text contains the streamed text, use the final text. If the streamed text contains the final text (preserving pre-tool-call content), keep the streamed text.
2. Lossy Stream Detection: If the stream is identified as a "lossy chunk-dropped copy" (using isLossyChunkCopy), the system replaces the garbled stream with the clean final_response.
3. Boundary Stitching: When merging a re-streamed boundary, it drops duplicated word-aligned seams.
4. Convergence: If a mangled stream (e.g., corrupted CJK) ends with the same substantial suffix as the final text, the system replaces the stream with the final text.
5. Fallback: If none of the above apply, it concatenates the two segments with a blank-line separator.

Note: On remote/SSH paths where renderAssistantDeltas: false, the bubble starts empty and the final text is used verbatim.

When using SSH mode, the desktop connects to a remote machine using one of two distinct transport methods depending on what is available on the remote:

1. Dashboard Transport (Preferred):

   • Purpose: Serves the model library, session lists (/api/*), and chat via WebSocket (/api/ws).
   • Port: Typically 9119 (or a dynamic port stored in HERMES_DESKTOP_DASHBOARD_PORT).
   • Authentication: Uses a HERMES_DASHBOARD_SESSION_TOKEN found in the remote .env.
   • Requirement: Requires a web distribution (Node/web dist) to be built on the remote.

2. Gateway /v1 Transport (Fallback):

   • Purpose: A "no-build" transport used when the dashboard is unavailable or the remote is a gateway-only install.
   • Port: 8642.
   • Authentication: Uses an API_SERVER_KEY found in the remote .env.
   • Capabilities: Serves /v1 chat endpoints (/v1/chat/completions, /v1/responses, /v1/runs) and /health.

Important: The dashboard is not a superset of the /v1 API. The gateway api_server does not proxy /v1 routes to the dashboard, and the dashboard provides surfaces (like the model library) that the gateway does not.

Every slash command is classified into a discriminated union with a target that determines how it is handled:

• desktop: Local UI actions or information displays (e.g., /settings, /new, /clear). These are handled by the Electron/renderer and do not send prompts upstream. Pure UI actions (flagged uiAction: true) suppress the echoed user bubble.
• agent: Commands that are forwarded upstream to the gateway via JSON-RPC.
• model: Commands (including Agent send/skill directives) that pass through a specific preparation layer before entering the standard chat transport. This is the only route allowed to submit model content.

Attachment Guard: Commands that route content upstream (agent or model) are gated and will be rejected if run with staged attachments unless they explicitly declare supportsAttachments. desktop commands are exempt from this guard.