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
# 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
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
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
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
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
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
# 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
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
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
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 autherneuert 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
# 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
# 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