File size: 14,012 Bytes
5134cea | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 | # 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
```
|