hermes-desktop-companion

# Hermes Desktop Companion > Skill by [ara.so](https://ara.so) — Hermes Skills collection. Hermes Desktop is a native Electron-based desktop application for installing, configuring, and interacting with [Hermes Agent](https://github.com/NousResearch/hermes-agent) — a self-improving AI assistant with tool use, multi-platform messaging, and closed learning loop. It provides a GUI alternative to CLI management with streaming chat, session management, profile switching, skill installation, memory editing, and gateway configuration. ## What It Does - **Guided installation**: First-run wizard installs Hermes Agent to `~/.hermes` with dependency resolution - **Local or remote mode**: Run Hermes locally on `127.0.0.1:8642` or connect to remote API server - **Multi-provider support**: OpenRouter, Anthropic, OpenAI, Google Gemini, xAI Grok, Nous Portal, Qwen, MiniMax, Hugging Face, Groq, and local OpenAI-compatible endpoints - **Streaming chat UI**: SSE-based real-time chat with tool progress, markdown rendering, syntax highlighting, token usage tracking - **22 slash commands**: `/new`, `/clear`, `/fast`, `/web`, `/image`, `/browse`, `/code`, `/shell`, `/usage`, `/help`, `/tools`, `/skills`, `/model`, `/memory`, `/persona`, `/version`, `/compact`, `/compress`, `/undo`, `/retry`, `/debug`, `/status` - **Profile management**: Multiple isolated Hermes environments with separate configs - **14 toolsets**: Web search, browser automation, terminal, file ops, code execution, vision, image gen, TTS, skills, memory, session search, clarify, delegation, MoA, task planning - **Memory system**: View/edit entries, user profile memory, capacity tracking, multiple providers (Honcho, Hindsight, Mem0, RetainDB, Supermemory, ByteRover) - **16 messaging gateways**: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, iMessage, DingTalk, Feishu, WeCom, WeChat, Webhooks, Home Assistant - **Session search**: Full-text search (SQLite FTS5) across conversation history - **Scheduled tasks**: Cron job builder with 15 delivery targets - **Hermes Office (Claw3d)**: Visual 3D interface with adapter management ## Installation ### Download Pre-built Binaries Download from [GitHub Releases](https://github.com/fathah/hermes-desktop/releases/): | Platform | File | |----------|------| | macOS | `.dmg` | | Linux (any) | `.AppImage` | | Debian/Ubuntu | `.deb` | | Fedora/RHEL | `.rpm` | | Windows | `.exe` (NSIS installer) | ### macOS Installation ```bash # After installing the .dmg, remove quarantine attribute xattr -cr "/Applications/Hermes Agent.app" ``` Or right-click → **Open** → confirm in dialog. ### Windows Installation Download `.exe` from releases. Windows SmartScreen will warn (unsigned) — click "More info" → "Run anyway". **Future winget support**: ```powershell winget install NousResearch.HermesDesktop ``` ### Linux Installation **AppImage** (universal): ```bash chmod +x hermes-desktop-*.AppImage ./hermes-desktop-*.AppImage ``` **Debian/Ubuntu**: ```bash sudo dpkg -i hermes-desktop-*.deb sudo apt-get install -f # Fix dependencies if needed ``` **Fedora/RHEL**: ```bash sudo dnf install ./hermes-desktop-*.rpm --nogpgcheck ``` ### WSL Passwordless Sudo (if installer stalls) ```bash echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/hermes-install # Re-run installer, then: sudo rm /etc/sudoers.d/hermes-install ``` ## First-Run Setup 1. **Choose deployment mode**: - **Local**: Installs Hermes to `~/.hermes`, runs on `127.0.0.1:8642` - **Remote**: Connect to existing Hermes API server (requires URL + API key) 2. **Local mode**: Installer checks for Git, uv, Python 3.11+, then runs official Hermes install script 3. **Configure provider**: Select from OpenRouter, Anthropic, OpenAI, Google, xAI, Nous Portal, Qwen, MiniMax, Hugging Face, Groq, or custom local endpoint 4. **Enter credentials**: API keys are saved to Hermes config files (not stored by desktop app) 5. **Launch workspace**: Main UI opens with Chat, Sessions, Agents, Skills, Memory, Tools, etc. ## Configuration ### Provider Configuration **Settings → Provider Config**: ```typescript // Example: OpenRouter setup { provider: "openrouter", apiKey: process.env.OPENROUTER_API_KEY, model: "anthropic/claude-3.5-sonnet", baseUrl: "https://openrouter.ai/api/v1" } // Example: Local Ollama { provider: "openai", apiKey: "not-needed", model: "llama3.1:8b", baseUrl: "http://localhost:11434/v1" } ``` ### Remote Mode Configuration **First run**: - Choose "Remote" mode - Enter API URL: `https://your-hermes-server.com` - Enter API key (from remote Hermes `/api/keys`) - App validates connection before proceeding ### Profile (Agent) Management **Agents screen**: - Create new profile: Creates isolated `~/.hermes/profiles/<name>` directory - Switch profile: Restarts Hermes with new profile context - Delete profile: Removes profile directory and data ```bash # Profiles stored at: ~/.hermes/profiles/ ├── default/ │ ├── config.yaml │ ├── SOUL.md │ ├── memory.db │ └── sessions.db └── work/ └── ... ``` ### Memory Provider Configuration **Memory screen → Configure Providers**: ```typescript // Example: Honcho { provider: "honcho", apiKey: process.env.HONCHO_API_KEY, appId: "hermes-desktop", userId: "user-123" } // Example: Mem0 { provider: "mem0", apiKey: process.env.MEM0_API_KEY, userId: "user-123" } ``` ### Gateway Configuration **Gateway screen** → Select platform → Configure: **Telegram**: ```yaml enabled: true bot_token: ${TELEGRAM_BOT_TOKEN} allowed_users: [123456789] ``` **Discord**: ```yaml enabled: true token: ${DISCORD_BOT_TOKEN} channel_ids: [1234567890123456789] ``` **Email (IMAP/SMTP)**: ```yaml enabled: true imap_server: imap.gmail.com imap_port: 993 smtp_server: smtp.gmail.com smtp_port: 587 username: ${EMAIL_USERNAME} password: ${EMAIL_APP_PASSWORD} ``` **WhatsApp** (via Baileys): ```yaml enabled: true session_path: ~/.hermes/whatsapp-session qr_code_callback: true ``` ## Chat Interface Usage ### Basic Chat Type naturally or use slash commands: ``` > What's the weather in San Francisco? [Hermes uses web search tool, returns answer] > /web latest news on AI regulation [Forces web search, streams results] > /image a cyberpunk city at sunset [Generates image via FAL.ai or configured provider] ``` ### Slash Commands | Command | Description | |---------|-------------| | `/new` | Start new conversation | | `/clear` | Clear current chat | | `/fast` | Switch to faster model | | `/web <query>` | Force web search | | `/image <prompt>` | Generate image | | `/browse <url>` | Browse and extract from URL | | `/code <task>` | Execute code task | | `/shell <command>` | Run shell command | | `/usage` | Show token usage stats | | `/help` | List all commands | | `/tools` | Show enabled tools | | `/skills` | List installed skills | | `/model [name]` | Get/set current model | | `/memory [query]` | Search memory | | `/persona` | Show current persona | | `/version` | Show Hermes version | | `/compact` | Compress chat history | | `/compress` | Deep compress with MoA | | `/undo` | Remove last message | | `/retry` | Retry last message | | `/debug` | Toggle debug mode | | `/status` | Show system status | ### Token Usage Tracking Bottom of chat shows live counts: ``` 📊 Prompt: 1,234 tokens • Completion: 567 tokens • Cost: $0.0123 ``` Use `/usage` for detailed breakdown: ``` > /usage Session Usage: Total Prompt Tokens: 12,345 Total Completion Tokens: 5,678 Total Cost: $0.123 Messages: 15 ``` ## Skills Management ### Installing Skills **Skills screen**: 1. Browse bundled skills (pre-installed with Hermes) 2. Or install from GitHub: ``` Repository: username/repo-name Branch: main (optional) ``` 3. Click **Install** ### Skill Structure Skills are markdown files with YAML frontmatter: ```markdown --- name: web-search-expert description: Expert at web searching and information retrieval triggers: - "search the web for" - "find information about" - "look up" --- # Web Search Expert Use the web_search tool to find current information... ## Examples When user asks: "What's the latest on GPT-5?" 1. Use web_search with query "GPT-5 latest news" 2. Summarize findings 3. Cite sources ``` ### Editing Skills **Skills screen** → Click skill → **Edit**: - Modify triggers, description, or content - Changes saved to `~/.hermes/skills/<name>/SKILL.md` ## Memory System ### Viewing Memory **Memory screen**: - **Memory Entries**: List of stored facts/context - **User Profile**: Persistent user information - **Capacity**: Current usage vs. limit ### Adding Memory Chat naturally — Hermes auto-saves important context: ``` > My name is Alice and I prefer Python over JavaScript [Hermes stores to memory automatically] > What's my name? [Hermes retrieves: "Alice"] ``` Or explicit: ``` > Remember I'm working on a TypeScript project called Hermes Desktop [Hermes: ✓ Stored to memory] ``` ### Editing Memory Entries **Memory screen**: 1. Click entry to view 2. Edit content or delete 3. Save changes ### Memory Providers Configured in **Memory screen → Configure Providers**: - **Honcho**: Managed memory service - **Hindsight**: Self-hosted memory - **Mem0**: Personalized AI memory - **RetainDB**: Vector memory DB - **Supermemory**: Context-aware memory - **ByteRover**: Local memory store ## Session Management ### Searching Sessions **Sessions screen**: - **Search bar**: Full-text search (SQLite FTS5) across all conversations - **Date groups**: Conversations grouped by Today, Yesterday, Last 7 Days, Last 30 Days, Older ```typescript // Example: Search sessions programmatically (if extending app) import { searchSessions } from './main/database'; const results = await searchSessions('typescript error handling'); // Returns: [{ id, title, timestamp, snippet, profileId }, ...] ``` ### Resuming Sessions 1. **Sessions screen** → Click conversation 2. Chat loads with full history 3. Continue conversation from last message ### Deleting Sessions Right-click session → **Delete** or click trash icon. ## Tools Management **Tools screen** → Enable/disable toolsets: | Toolset | Capabilities | |---------|--------------| | **web** | Exa/Tavily search, Firecrawl scraping | | **browser** | Playwright automation, screenshot, PDF | | **terminal** | Shell command execution | | **file** | Read, write, list, move files | | **code** | Python execution in sandbox | | **vision** | Image analysis (GPT-4V, Claude Vision) | | **image** | Generation via FAL.ai/DALL-E | | **tts** | Text-to-speech synthesis | | **skills** | Install/manage skills | | **memory** | Store/retrieve context | | **session** | Search past conversations |