In dem Moment, in dem ein Chat aufgeht, sollten Plugins es schon wissen: Hermes bekommt den on_session_open Hook


Neun Uhr morgens. Du öffnest Hermes Desktop und nimmst die Arbeit von gestern im selben Repo wieder auf. Dein Memory-Plugin hält die Schlussfolgerung schon bereit — welcher Endpoint von Anfang an falsch konfiguriert war, welche Testdatei sich als Zeitverschwendung erwiesen hat. Aber es hat keine Ahnung, dass du zurück bist. Es erfährt erst, dass eine Unterhaltung existiert, wenn du die erste Nachricht tippst und sie durch das Modell läuft.

Der andere Fall ist schlimmer. Du öffnest das Fenster, scrollst zwei Bildschirme durch den Chat von gestern, schließt es wieder. Das Plugin hört überhaupt nichts, weil die neue Nachricht, auf die es gewartet hat, nie kommt.

Plugin-Autoren reagieren meist gleich: pollen. Alle paar Sekunden aufwachen, das Session-Verzeichnis auflisten, Änderungszeiten prüfen. Das funktioniert, ist aber hässlich — Polling kann nicht sagen, ob du wirklich zurückgekommen bist, und es kann eine frische session nicht von einer wieder geöffneten unterscheiden.

on_session_open existiert, um genau diese Lücke zu schließen.

Einen ganzen Turn früher als on_session_start

Hermes hatte bereits einen ähnlich benannten Hook: on_session_start. Fast derselbe Name, ein ganz anderer Auslösezeitpunkt — dieser feuert innerhalb des ersten Agent-Turns, also wenn eine echte Nutzernachricht gerade verarbeitet werden soll.

Wenn du einen gespeicherten Chat wieder öffnest, feuert on_session_start also nie. Selbst wenn du weiterredest, feuert nicht „diese session wurde geöffnet“, sondern „dieser Turn hat begonnen“.

on_session_open ist das Zweite: der Moment, in dem eine session erzeugt oder geöffnet wird, bevor das Modell irgendetwas sieht. Die Docs sind beim Intent explizit — es geht darum, sich auf eine Unterhaltung vorzubereiten, zum Beispiel ein Memory-Plugin, das die letzten zwanzig Notizen vorlädt, oder eine Statusleiste, die die session sofort als offen markiert.

Was der Auslösezeitpunkt tatsächlich bedeutet

Die Details zählen, denn sie entscheiden, ob dein callback bei einem Klick zweimal läuft.

Gefeuert wird er von der session-Autorität des gateway: Wenn eine Client-Verbindung sich an eine lokale session anhängt, an die sie noch nicht angehängt war, feuert er einmal. Das gibt dir saubere Kanten:

  • Ein Öffnen, ein Feuern. Ein Client, der einen Snapshot einer session neu liest, die er schon hält, feuert ihn nicht. Ein Reconnect nach einem abgebrochenen Socket feuert ihn nicht. Du brauchst kein Dedup-Set.
  • Zwei Clients, die dieselbe session öffnen, feuern zweimal. Das sind zwei echte Öffnungen, und Plugins sollten wissen, dass zwei Leute angekommen sind.
  • Erzeugen und Fortsetzen zählen beide, unterschieden über reason: create, solange die session noch keine Nachrichten hat, resume, sobald sie eine Unterhaltung hat.
  • Er läuft in dem profile, dem die session gehört. Auf einem gateway, das mehrere profile bedient, sehen die Plugins jedes profile nur ihre eigenen sessions — kein Cross-Talk.
  • Messaging-Chats feuern ihn nicht. Telegram, Discord und ihresgleichen haben keine „Öffnen“-Aktion; ihre sessions beginnen mit der ersten Nachricht, und on_session_start bleibt dort der richtige Hook.

Der payload ist klein: session_id, platform (cli, tui, desktop, acp und so weiter) und reason (create oder resume). Kein Nachrichteninhalt, keine Nutzereingabe — bewusst, damit du dir hier nie Gedanken über Privacy machen musst.

Einen callback schreiben: erst den Cache wärmen

Innerhalb eines Plugins ist die Registrierung wie bei jedem anderen Hook:

# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}

def warm(session_id, platform, reason, **kwargs):
    # Nur billige Vorbereitung: Dateien lesen, lokalen Index abfragen, State schreiben
    _cache[session_id] = load_recent_notes(limit=20)

def register(ctx):
    ctx.register_hook("on_session_open", warm)

Lass **kwargs nicht weg. Felder kommen im Laufe der Zeit dazu, und eine fest verdrahtete Signatur trifft irgendwann auf ein neues Feld und wird zum TypeError.

Das Einzige, was in diesem Snippet auffällt: Der callback läuft im gateway, nicht im Client. Wenn die klassische CLI, die TUI oder Desktop eine session öffnen, lädt und startet der gateway-Prozess den Plugin-Code; der Client-Prozess fasst Plugins nie an. Das ist eine Sicherheitsgrenze, und deshalb zeigen die Log-Zeilen auch die pid des gateway.

Du musst kein Python schreiben. Shell-Hooks unterstützen dieses Event ebenfalls:

# ~/.hermes/config.yaml
hooks:
  on_session_open:
    - command: "~/.hermes/agent-hooks/session-open.sh"
      timeout: 10

Das Skript bekommt einen JSON-payload auf stdin mit diesen drei Feldern. Um eine Audit-Zeile anzuhängen oder einen lokalen Service anzupingen, reichen ein Dutzend Zeilen bash.

Dann teste es. hermes hooks test deckt dieses Event ab: Es feuert jeden passenden Hook gegen einen synthetischen payload und gibt die geparste Antwort aus.

hermes hooks test on_session_open

Ein Fünf-Sekunden-Budget, und die Regel daraus

Es gibt einen Design-Trade-off, den man kennen sollte: Das Öffnen der session wartet nie auf Plugins, der nächste Turn der session aber schon.

Konkret: Der callback wird auf einem eigenen Thread dispatcht, der Klick auf Öffnen ist also sofort. Aber bevor der Turn wirklich startet, wartet er auf den callback — bis zu 5 Sekunden, oder länger, wenn plugins.hook_callback_timeout (Standard 30 Sekunden) höher gesetzt ist. Danach läuft der Turn weiter, und der callback läuft im Hintergrund weiter.

plugins.hook_callback_timeout auf 0 zu setzen bedeutet, dass callbacks nie abgebrochen werden. Auch dann wartet der Turn nur 5 Sekunden: Die Einstellung heißt „langsame callbacks nicht killen“, nicht „sie die Unterhaltung als Geisel halten lassen“.

Daraus folgt die Regel: Halte den callback schnell. Lokale Dateien lesen, eine SQLite-Query, einen In-Memory-Cache füllen — alles im Budget. Ein LLM aufrufen, eine Remote-API treffen, ein Repository scannen — damit legst du Latenz auf die erste Zeile des Nutzers.

Zwei weitere Details:

  • Wenn der callback einer session noch läuft und dieselbe session erneut geöffnet wird, hängt sich die neue Öffnung an und feuert einmal, wenn die erste fertig ist, mit den Details der neuesten Öffnung. Ein hängender callback kann nicht zehn Threads aufstauen.
  • Enthalten die geladenen Plugins des profile überhaupt keinen Subscriber, passiert nichts — nicht einmal ein Thread.

Fehler sind fail-open: Eine Exception wird geloggt und übersprungen, spätere callbacks laufen weiter, und die session öffnet trotzdem.

Was hier hingehört, und was nicht

Gut passen die Fälle „die Unterhaltung hat noch nicht begonnen, aber ich will bereit sein“:

  • Memory- oder Knowledge-Base-Warm-up: die Notizen und Schlussfolgerungen zu diesem Repo ziehen, damit schon die erste Nachricht davon profitiert.
  • State und Signale: Statusleisten, externe Dashboards, Audit-Logs. „Wer hat welche session wann geöffnet“ ist eine Zeile, die Operatoren wirklich wollen.
  • Credentials oder Arbeitsverzeichnisse pro session: Plugins, die wissen müssen, zu welchem Projekt eine session gehört, bevor sie eine Konfiguration wählen.
  • Reste der letzten Runde aufräumen: bei einer create-Öffnung alte Drafts zu verwerfen ist verlässlicher als raten.

Die schlechten Fits sind genauso klar:

  • „Session started“ auf Messaging-Plattformen — nutze on_session_start.
  • Alles, was Nutzereingabe braucht; zu diesem Zeitpunkt gibt es keine.
  • Jeder Netzwerk-Roundtrip, der in Hunderten von Millisekunden gemessen wird.

Ein Hinweis zum Scoping: sessions, die mit --safe-mode oder --ignore-user-config gestartet wurden, feuern ihn nie, weil Plugins in diesen Modi nicht geladen werden.

Kann ich das heute nutzen?

Der Hook wurde am 8. November 2026 nach main gemergt (PR #151120). Ich habe geprüft, was v0.23.0 ausgeliefert hat: Dieses Release ging am 6. November raus, der Hook ist also nicht in v0.23.0. Er ist main-only und erreicht mit der nächsten Version ein stabiles Release.

Update (10.11.2026): Diese Änderungen sind mit v0.23.1 (9. November) erschienen – ein hermes update genügt. Die Aussage „nicht in v0.23.0“ oben stimmt weiterhin; v0.23.1 schließt die Lücke.

Wenn du main fährst, kannst du ihn jetzt nutzen. Bist du auf einem stabilen Release, schreib das Plugin und beweise die Logik mit hermes hooks test, damit es am Tag des Upgrades funktioniert.

Bis dahin decken die älteren Hooks einen Teil des Bodens ab: on_session_start für den ersten Turn, plus die session-boundary-Hooks aus den Plugin-Notifications für komprimierte und gelöschte sessions. Dieselbe Dispatch-Maschinerie kann auch einen ganzen Turn vor dem Modellaufruf blockieren — siehe den pre_llm_call Policy-Hook — und die Command-Referenz listet jeden unterstützten Event-Namen und jedes Config-Feld.

Die Kurzfassung

on_session_open schließt eine bestimmte Lücke: „die session ist offen, aber noch keine Nachricht angekommen.“ Genau in diesem Moment waren Plugins bisher blind. Jetzt bekommen sie session_id, platform und reason, plus fünf Sekunden zum Vorbereiten. Die einzige Regel, die man sich merken muss, ist die, die das Budget impliziert: in diesen fünf Sekunden die billigen Dinge tun, die teuren dem ersten Turn überlassen.