| # Hermes Harness — Referenz für AI Engineers |
|
|
| > Zielgruppe: Samuel (kennt Claude Code gut, kennt Hermes nicht). Fokus: Architektur-Unterschiede, Konfiguration, Tuning, ehrliche Bewertung. |
|
|
| --- |
|
|
| ## 1. Architektur (fundamental anders als Claude Code) |
|
|
| Hermes ist kein natives API-Harness wie Claude Code, sondern ein **Multi-Platform Agent-Gateway** mit eigenem REPL, Session-DB, Memory-System und Skills-Hub. Der zentrale Unterschied: Claude Code ist eine CLI mit Hook-System; Hermes ist ein verteiltes System, das über mehrere Kanäle (CLI, Telegram, Discord, Slack, WhatsApp, Signal, HomeAssistant) auf demselben Backend läuft. |
|
|
| ``` |
| config.yaml (284 Zeilen) ← Haupt-Config (YAML, nicht JSON) |
| ↓ |
| SOUL.md ← Agent-Personality (freier Text) |
| ↓ |
| Multi-Platform Gateway ← CLI + 6 Messaging-Plattformen |
| ↓ |
| Model Router (10 Provider) ← agnostisch, OpenRouter = 200+ Modelle |
| ↓ |
| 48 eingebaute Tools ← Web, Terminal, Vision, Browser, SmartHome |
| ↓ |
| SQLite (state.db) + Honcho AI ← persistente Sessions + Cross-Session Memory |
| ``` |
|
|
| **Direktvergleich Claude Code vs. Hermes:** |
|
|
| | Aspekt | Claude Code | Hermes | |
| |--------|-------------|--------| |
| | Interaktion | CLI REPL | CLI REPL + 6 Messaging-Plattformen | |
| | Model-Lock | Anthropic only | 200+ Modelle, 10 Provider, Custom Endpoints | |
| | Config-Format | JSON (settings.json) | YAML (config.yaml, 284 Zeilen) | |
| | Verhaltenssteuerung | CLAUDE.md (deklarativ) | SOUL.md (freier Text, aktuell leer) | |
| | Hook-System | 5 Lifecycle-Points, PreToolUse blockierend | Keins — kein Blocking-Gate | |
| | Tools | MCP-basiert (extern) | 48 eingebaut (Web, Terminal, Vision, Browser, SmartHome) | |
| | Terminal-Execution | Lokal only | 6 Backends: local, docker, ssh, modal, singularity, daytona | |
| | Parallelism | Subagents (separate Prozesse) | Git Worktrees (isolierte Branches, gleiches Repo) | |
| | Memory | Kein Cross-Session Memory | Honcho AI + auto-save (cross-session persistent) | |
| | Skills | Statisch (SKILL.md Injection) | Dynamisch, selbst-lernend, Skills Hub (26 Kategorien) | |
| | Session-Storage | JSON-Dateien | SQLite + FTS5 Full-Text Search (21 Sessions) | |
| | Personality | CLAUDE.md Regeln | SOUL.md + 14 Personality-Varianten | |
| | Cron/Scheduling | Kein Scheduler | Eingebaut | |
|
|
| **Was das in der Praxis bedeutet:** |
|
|
| Claude Code ist eng mit Anthropic verzahnt — Anthropic-Modelle, MCP für externe Tools, JSON-Config. Hermes ist bewusst model-agnostisch und plattform-agnostisch gebaut. Wer Hermes kennt, kann mit einem Flag auf Opus wechseln oder den gleichen Agent über Telegram ansprechen. Wer Claude Code kennt, muss sich vor allem an drei Dinge gewöhnen: kein PreToolUse-Blocking, kein CLAUDE.md-Äquivalent und ein träger Start (10-15 Sekunden Stille vor der ersten Response — das ist normal, nicht abbrechen). |
|
|
| --- |
|
|
| ## 2. Konfiguration |
|
|
| ### Haupt-Config: `~/.hermes/config.yaml` |
|
|
| ```yaml |
| # Modell-Defaults |
| default_model: MiniMax-M2.5 |
| default_provider: minimax |
| |
| # Agent-Verhalten |
| agent: |
| max_turns: 100 |
| reasoning_effort: medium # low | medium | high |
| personalities: [helpful, concise, technical] |
| |
| # Terminal-Backend |
| terminal: |
| backend: local # local | docker | ssh | modal | singularity | daytona |
| cwd: . |
| timeout: 180 |
| persistent_shell: true |
| |
| # Cross-Session Memory |
| memory: |
| enabled: true |
| user_char_limit: 2200 |
| profile_char_limit: 1375 |
| |
| # Kontext-Kompression |
| compression: |
| enabled: true |
| summary_model: google/gemini-3-flash-preview |
| |
| # Sicherheit |
| security: |
| redact_secrets: true |
| tirith_enabled: true |
| ``` |
|
|
| **Wichtig:** `terminal.cwd: .` bedeutet Hermes arbeitet im Verzeichnis, von dem aus es gestartet wird. Wird Hermes ohne explizites cwd gestartet, baut es in `~/.hermes/` — das ist der häufigste Scope-Drift-Fehler. Immer aus dem Projektordner starten oder cwd explizit setzen. |
|
|
| ### Weitere Config-Dateien |
|
|
| | Datei | Inhalt | |
| |-------|--------| |
| | `~/.hermes/.env` | API Keys (OPENROUTER_API_KEY, MINIMAX_API_KEY, FIRECRAWL_API_KEY, FAL_KEY, HONCHO_API_KEY, SSH-Credentials) | |
| | `~/.hermes/auth.json` | OAuth Tokens (Nous, OpenAI-Codex) | |
| | `~/.hermes/SOUL.md` | Agent-Personality, freier Text — aktuell leer | |
| | `~/.hermes/state.db` | SQLite Session-DB | |
| | `~/.hermes/memories/` | Cross-Session Memory-Dateien | |
| | `~/.hermes/skills/` | 26 Skill-Kategorien | |
| | `~/.hermes/sessions/` | Session JSON-Archive | |
| | `~/.hermes/hermes-agent/` | Vollständiger Source-Code | |
| |
| --- |
| |
| ## 3. Tuning |
| |
| ### Modell wechseln |
| |
| ```bash |
| hermes model # Interaktive Auswahl |
| hermes chat --model anthropic/claude-opus-4.6 # Inline spezifizieren |
| hermes chat -m google/gemini-2.5-pro # Kurzform |
| hermes chat --provider openrouter # Provider forcen |
| ``` |
| |
| **Verfügbare Provider (10):** |
| |
| | Provider | Besonderheit | |
| |----------|-------------| |
| | MiniMax | Default, günstigst (~$0.01-0.20/Task) | |
| | OpenRouter | Gateway zu 200+ Modellen | |
| | Anthropic | Direktzugriff (Claude-Familie) | |
| | Nous Portal | OAuth-basiert | |
| | OpenAI Codex | OAuth (Token aktuell abgelaufen — 401) | |
| | z.ai / GLM | Chinesischer Provider | |
| | Kimi / Moonshot | Chinesischer Provider | |
| | MiniMax China | Mainland-Endpoint | |
| | Google Gemini | Via OpenRouter | |
| | Custom Endpoints | Beliebige OpenAI-kompatible APIs | |
| |
| ### Terminal-Backend wechseln |
| |
| ```bash |
| hermes config set terminal.backend docker # Container-Isolierung |
| hermes config set terminal.backend ssh # Remote Execution |
| hermes config set terminal.backend modal # Serverless, pay-per-use |
| hermes config set terminal.backend local # Zurück zu lokal |
| ``` |
| |
| Docker und SSH sind nützlich wenn Hermes Code in einer sauberen Umgebung ausführen soll, ohne das Host-System zu beeinflussen. Modal rechnet serverless ab — sinnvoll für sporadische schwere Tasks. |
| |
| ### Parallele Tasks mit Git Worktrees |
| |
| ```bash |
| hermes chat --worktree # Auto-generierter Worktree-Name |
| hermes chat --worktree feature-auth # Benannter Worktree |
| hermes chat -w # Kurzform |
| ``` |
| |
| Das ist Hermes' Äquivalent zu Claude Code's Subagents — aber anders: statt separater Prozesse arbeitet Hermes in isolierten Git-Branches auf demselben Repo. Merge muss danach manuell passieren. |
| |
| ### Skills verwalten |
| |
| ```bash |
| hermes skills browse # Alle verfügbaren Skills |
| hermes skills search "web" # Suchen |
| hermes skills install <name> # Installieren |
| hermes skills list # Installierte anzeigen |
| hermes skills update # Updates einspielen |
| hermes skills audit # Security-Audit |
| ``` |
| |
| Hermes-Skills sind nicht dasselbe wie Sidecar-NG Skills. Sie werden dynamisch aus Nutzungsmustern erstellt und verbessern sich selbst — ein anderes Konzept als statische SKILL.md Injection. |
| |
| ### Sessions verwalten |
| |
| ```bash |
| hermes sessions list # Alle Sessions |
| hermes sessions stats # Nutzungsstatistiken |
| hermes sessions export <id> # Session exportieren |
| hermes sessions prune # Alte Sessions aufräumen |
| hermes chat --continue # Letzte Session fortsetzen |
| hermes chat --resume <id> # Spezifische Session laden |
| ``` |
| |
| Da Sessions in SQLite mit FTS5 gespeichert sind, ist die Suche über alte Sessions schneller und robuster als bei JSON-basierten Ansätzen. |
| |
| ### Personality konfigurieren |
| |
| ```bash |
| # Variante 1: config.yaml |
| agent: |
| personalities: [concise, technical] |
| |
| # Variante 2: SOUL.md editieren |
| # ~/.hermes/SOUL.md — freier Text, wird als Systemprompt eingebettet |
| ``` |
| |
| Aktuell ist SOUL.md leer — das Potenzial ist ungenutzt. Die 14 verfügbaren Personality-Varianten sind: helpful, concise, technical, kawaii, pirate (und weitere). Das ist näher an einem Charakter-System als an CLAUDE.md-Regeln. |
| |
| ### Reasoning-Tiefe einstellen |
| |
| ```bash |
| hermes config set agent.reasoning_effort high # Mehr Tokens, langsamer, besser bei Analyse |
| hermes config set agent.reasoning_effort low # Schnell, für einfache Tasks |
| ``` |
| |
| ### Diagnose und Monitoring |
| |
| ```bash |
| hermes doctor # System-Check (Config, Auth, Dependencies) |
| hermes insights # Usage Analytics |
| hermes config show # Aktuelle Config ausgeben |
| hermes config set <key> <value> # Einzelnen Wert setzen |
| ``` |
| |
| ### Multi-Platform Gateway starten |
| |
| ```bash |
| hermes gateway # Telegram, Discord, Slack, WhatsApp, Signal, HomeAssistant |
| ``` |
| |
| Derselbe Agent, der lokal im Terminal läuft, ist dann über alle konfigurierten Messaging-Plattformen erreichbar. Config dafür liegt ebenfalls in config.yaml. |
| |
| --- |
| |
| ## 4. Vor- und Nachteile |
| |
| ### Vorteile |
| |
| - **Günstigster Harness**: MiniMax als Default kostet ~$0.01-0.20 pro Task — ca. 150x günstiger als Opus direkt. Für explorative Tasks oder Drafts sinnvoll. |
| - **Model-Agnostisch**: 10 Provider, 200+ Modelle via OpenRouter, Custom Endpoints. Modell-Wechsel ist ein Flag, keine Architektur-Entscheidung. |
| - **Beste Feedback-Annahme**: Eval-Befund: "Fehler präzise akzeptiert, sofort weitergebaut" — kein anderes getestetes Harness nimmt Korrekturen so direkt an. |
| - **6 Terminal-Backends**: Docker, SSH, Modal, Singularity, Daytona — nicht auf lokale Execution beschränkt. Remote-Execution ohne zusätzliches Tooling. |
| - **Git Worktrees first-class**: Parallele isolierte Agents auf demselben Repo per Flag. |
| - **Cross-Session Memory**: Honcho AI merkt sich Kontext über Sessions. Claude Code vergisst nach Sessionende alles. |
| - **Multi-Platform out of the box**: Dieselbe Konfiguration, dieselben Skills, über CLI und 6 Messaging-Plattformen. |
| - **48 eingebaute Tools**: Web-Suche, Browser-Automation, Vision, Image Gen, Smart Home — ohne MCP-Server aufsetzen zu müssen. |
| - **Selbst-lernende Skills**: Werden aus Erfahrung erstellt und verbessert, nicht manuell gepflegt. |
| - **SQLite + FTS5**: Sessions sind durchsuchbar. |
| - **Eingebauter Scheduler**: Cron-Jobs ohne externe Tools. |
| |
| ### Nachteile |
| |
| - **Scope-Drift Hauptproblem**: Baut standardmäßig in `~/.hermes/` wenn cwd nicht gesetzt ist. Immer aus dem Projektordner starten. |
| - **Langsamer Start**: 10-15 Sekunden Stille vor der ersten Response — das ist kein Hänger, sondern normales Verhalten. Nicht abbrechen. |
| - **Output-Qualität mittel**: Funktionierender aber nicht eleganter Code. Polishing durch einen Codex-Pass sinnvoll. |
| - **Intransparenter Prozess**: Hermes denkt intern, Output kommt plötzlich als Block. Was intern passiert ist kaum sichtbar — kein Streaming wie Claude Code. |
| - **Kein Hook-System**: Kein PreToolUse-Blocking, kein 5-Punkt-Lifecycle. Verhaltenssteuerung nur über SOUL.md und Prompting — nicht programmatisch erzwingbar. |
| - **Kein CLAUDE.md-Äquivalent**: Keine deklarative, dateibasierte Verhaltenssteuerung. SOUL.md ist freier Text, keine strukturierten Regeln. |
| - **SOUL.md aktuell leer**: Die Personality-Konfiguration ist ungenutzt — das ist verpasstes Potenzial. |
| - **OpenAI Codex Token expired**: OAuth-Token abgelaufen (401 Error). Muss über `hermes auth` erneuert werden bevor Codex-Provider nutzbar ist. |
| - **ripgrep nicht installiert**: Hermes fällt auf grep-Fallback zurück — langsamer bei Code-Suche in großen Repos. |
| - **Kein Sidecar-Equivalent**: Keine Context-Injection vor dem LLM-Call, kein Classifier-Layer. |
| |
| --- |
| |
| ## 5. Referenz |
| |
| ### Wichtige Dateipfade |
| |
| ``` |
| ~/.hermes/config.yaml Haupt-Config (284 Zeilen, alle Einstellungen) |
| ~/.hermes/.env API Keys und Secrets |
| ~/.hermes/auth.json OAuth Tokens (Nous, OpenAI-Codex) |
| ~/.hermes/SOUL.md Agent-Personality (freier Text, aktuell leer) |
| ~/.hermes/state.db SQLite Session-DB (21 Sessions) |
| ~/.hermes/sessions/ Session JSON-Archive |
| ~/.hermes/skills/ 26 Skill-Kategorien |
| ~/.hermes/memories/ Cross-Session Memory |
| ~/.hermes/hermes-agent/ Vollständiger Source-Code |
| ``` |
| |
| ### Wichtige Befehle |
| |
| ```bash |
| # Sessions |
| hermes chat Interaktive Session starten |
| hermes chat -q "prompt" Single Query (non-interactive) |
| hermes chat -w In Worktree (parallel, isoliert) |
| hermes chat -m provider/model Modell überschreiben |
| hermes chat --checkpoints Mit Filesystem-Snapshots |
| hermes chat --continue Letzte Session fortsetzen |
| hermes chat --resume <id> Spezifische Session laden |
| |
| # Config & Modell |
| hermes model Modell interaktiv wählen |
| hermes config show Aktuelle Config anzeigen |
| hermes config set <key> <value> Einzelnen Wert setzen |
| |
| # Skills |
| hermes skills browse Alle verfügbaren Skills |
| hermes skills search "query" Skills suchen |
| hermes skills install <name> Skill installieren |
| hermes skills list Installierte Skills anzeigen |
| hermes skills update Skills aktualisieren |
| hermes skills audit Security-Audit |
| |
| # Sessions |
| hermes sessions list Alle Sessions auflisten |
| hermes sessions stats Nutzungsstatistiken |
| hermes sessions export <id> Session exportieren |
| hermes sessions prune Alte Sessions aufräumen |
| |
| # System |
| hermes gateway Multi-Platform Gateway starten |
| hermes doctor System-Diagnose |
| hermes insights Usage Analytics |
| hermes update Self-Update |
| ``` |
| |
| ### Quickstart für einen neuen Task |
| |
| ```bash |
| # 1. Aus dem Projektordner starten (verhindert Scope-Drift) |
| cd ~/Projekte/mein-projekt |
| |
| # 2. Hermes starten (15s Stille am Anfang ist normal) |
| hermes chat |
| |
| # 3. Oder direkt mit Modell-Override für komplexe Tasks |
| hermes chat -m anthropic/claude-opus-4.6 |
| |
| # 4. Parallelen Task in Worktree |
| hermes chat -w feature-xyz |
| ``` |
| |
