The moment a chat opens, plugins should already know: Hermes adds the on_session_open hook

Nine in the morning. You open Hermes Desktop and pick up yesterday’s work in the same repo. Your memory plugin already holds the conclusion you reached — which endpoint was misconfigured from the start, which test file turned out to be a waste of time. But it has no idea you are back. It only learns that a conversation exists when you type the first message and it passes through the model.
The other case is worse. You open the window, scroll two screens through yesterday’s chat, close it. The plugin hears nothing at all, because the new message it was waiting for never comes.
Plugin authors usually react the same way: poll. Wake up every few seconds, list the sessions directory, look at modification times. It works, but it is ugly — polling cannot tell whether you actually came back, and it cannot tell a fresh session from a reopened one.
on_session_open exists to close that gap.
A full turn earlier than on_session_start
Hermes already had a similarly named hook: on_session_start. Almost the same name, a very different firing point — that one fires inside the first agent turn, meaning a real user message is about to be processed.
So when you reopen a saved chat, on_session_start never fires. Even if you keep talking, what fires is “this turn started,” not “this session was opened.”
on_session_open is the second thing: the moment a session is created or opened, before the model sees anything. The docs are explicit about the intent — it is for getting ready for a conversation, for example a memory plugin pre-loading the last twenty notes, or a status bar immediately marking the session as open.
What the firing point actually means
The details matter, because they decide whether your callback runs twice for one click.
It is fired by the gateway’s session authority: when a client connection attaches to a local session it was not already attached to, it fires once. That gives you clean edges:
- One open, one fire. A client re-reading a snapshot of a session it already holds does not fire it. Reconnecting after a dropped socket does not fire it. You do not need to maintain a dedup set.
- Two clients opening the same session fire twice. Those are two real opens, and plugins should know two people arrived.
- Creating and resuming both count, distinguished by
reason:createwhile the session has no messages yet,resumeonce it has a conversation. - It runs in the profile that owns the session. On a gateway serving several profiles, each profile’s plugins see only their own sessions — no cross-talk.
- Messaging chats do not fire it. Telegram, Discord and friends have no “open” action; their sessions begin with the first message, and
on_session_startremains the right hook there.
The payload is small: session_id, platform (cli, tui, desktop, acp, and so on), and reason (create or resume). No message content, no user input — deliberately, so you never have to think about privacy here.
Writing a callback: warm the cache first
Inside a plugin, the registration is the same as any other hook:
# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}
def warm(session_id, platform, reason, **kwargs):
# Cheap preparation only: read files, query a local index, write state
_cache[session_id] = load_recent_notes(limit=20)
def register(ctx):
ctx.register_hook("on_session_open", warm)
Do not drop **kwargs. Fields get added over time, and a hard-coded signature eventually meets a new field and turns into a TypeError.
The one thing worth noticing in that snippet: the callback runs in the gateway, not in the client. When the classic CLI, the TUI or Desktop opens a session, the gateway process loads and runs the plugin code; the client process never touches plugins. That is a security boundary, and it is also why the log lines show the gateway’s pid.
You do not have to write Python. Shell hooks support this event too:
# ~/.hermes/config.yaml
hooks:
on_session_open:
- command: "~/.hermes/agent-hooks/session-open.sh"
timeout: 10
The script gets a JSON payload on stdin with those three fields. For appending an audit line or pinging a local service, a dozen lines of bash is plenty.
Then test it. hermes hooks test covers this event: it fires every matching hook against a synthetic payload and prints the parsed response.
hermes hooks test on_session_open
A five-second budget, and the rule that follows
There is a design trade-off worth knowing: opening the session never waits on plugins, but the session’s next turn does.
Concretely, the callback is dispatched on its own thread, so the moment you click open is instant. But before the turn actually starts, it waits for the callback — up to 5 seconds, or longer if plugins.hook_callback_timeout (default 30 seconds) is set higher. Past that, the turn proceeds and the callback keeps running in the background.
Setting plugins.hook_callback_timeout to 0 means callbacks are never abandoned. Even then the turn waits only 5 seconds: that setting means “do not kill slow callbacks,” not “let them hold the conversation hostage.”
Which leads to the rule: keep the callback fast. Reading local files, one SQLite query, filling an in-memory cache — all within budget. Calling an LLM, hitting a remote API, scanning a repository — you are now adding latency to the user’s opening line.
Two more details:
- If a session’s callback is still running and the same session is opened again, the new open joins it and fires once when the first finishes, with the latest open’s details. A stuck callback cannot pile up ten threads.
- If the profile’s loaded plugins contain no subscriber at all, nothing happens — not even a thread.
Failures are fail-open: an exception is logged and skipped, later callbacks continue, and the session opens regardless.
What belongs here, and what does not
Good fits are the “the conversation has not started, but I want to be ready” cases:
- Memory or knowledge-base warm-up: pull the notes and conclusions tied to this repo so the first message already benefits.
- State and signals: status bars, external dashboards, audit logs. “Who opened which session, and when” is a line operators genuinely want.
- Per-session credentials or working directories: plugins that need to know which project a session belongs to before choosing a configuration.
- Clearing leftovers from the last round: on a
createopen, dropping stale drafts is more reliable than guessing.
The bad fits are just as clear:
- “Session started” on messaging platforms — use
on_session_start. - Anything that needs user input; at this point there is none.
- Any network round-trip measured in hundreds of milliseconds.
One scoping note: sessions started with --safe-mode or --ignore-user-config never fire it, because plugins are not loaded in those modes.
Can I use it today?
The hook merged to main on November 8, 2026 (PR #151120). I checked what v0.23.0 shipped: that release went out on November 6, so this hook is not in v0.23.0. It is main-only code and will reach a stable release with the next version.
Update (2026-11-10): these changes shipped in v0.23.1 (November 9) —
hermes updateis enough. The “not in v0.23.0” statements above are still accurate; v0.23.1 closes the gap.
If you run main, you can use it now. If you are on a stable release, write the plugin and prove the logic with hermes hooks test, so it works the day you upgrade.
Until then, the older hooks still cover part of the ground: on_session_start for the first turn, plus the session-boundary hooks we covered in the plugin notifications for compacted and deleted sessions. The same dispatch machinery can also block a whole turn before the model call — see the pre_llm_call policy hook — and the command reference lists every supported event name and config field.
The short version
on_session_open fills one specific gap: “the session is open, but no message has arrived yet.” Plugins used to be blind in exactly that moment. Now they get session_id, platform and reason, plus five seconds to prepare. The only rule to remember is the one the budget implies: do cheap things in those five seconds, and leave the expensive ones to the first turn.