Event Hooks — Auto-Trigger at Key Moments

Think of event hooks like a smart doorbell that not only rings when someone arrives, but also automatically unlocks the door, turns on the lights, and texts you a photo — all without you lifting a finger.

In Hermes Agent, event hooks are small pieces of code that run automatically at specific moments in your agent’s life. Instead of manually checking “did the agent finish?” or “did a new chat start?”, you can set up hooks to do something useful at exactly the right time.

Four Ways to Hook In

Hermes gives you four different hook systems, each with its own job:

System	Best for
Gateway hooks	Logging, alerts, webhooks (Gateway only)
Plugin hooks	Tool interception, metrics, guardrails (CLI + Gateway)
Shell hooks	Drop-in scripts for blocking, auto-formatting (CLI + Gateway)
Outbound webhooks	Push signed events to external HTTP endpoints (CLI + Gateway)

Don’t worry about memorizing all four. Start with Gateway hooks — they’re the easiest to understand.

Your First Gateway Hook

Gateway hooks live in ~/.hermes/hooks/. Each hook is a folder with two files:

~/.hermes/hooks/
└── my-hook/
    ├── HOOK.yaml      # Tells Hermes which events to listen for
    └── handler.py     # The code that runs when an event fires

Step 1: Declare Events in HOOK.yaml

name: my-hook
description: Log all agent activity to a file
events:
  - agent:start
  - agent:end

Step 2: Write the Handler

import json
from datetime import datetime
from pathlib import Path

LOG_FILE = Path.home() / ".hermes" / "hooks" / "my-hook" / "activity.log"

async def handle(event_type: str, context: dict):
    entry = {
        "timestamp": datetime.now().isoformat(),
        "event": event_type,
        **context,
    }
    with open(LOG_FILE, "a") as f:
        f.write(json.dumps(entry) + "\n")

Three simple rules for handlers:

• The function must be named handle
• It receives event_type (a string) and context (a dictionary)
• It can be async or regular — both work

What Can You Listen For?

Here are some useful events:

Event	When it fires
gateway:startup	Gateway process starts
session:start	New chat session begins
session:reset	User runs /new
agent:start	Agent starts processing a message
agent:end	Agent finishes processing

You can even use wildcards like command:* to catch a whole family of events.

The Best Part: Hooks Can’t Crash Your Agent

If your hook code has a bug, Hermes catches the error, logs it, and moves on. Your agent keeps working. This means you can experiment freely without fear of breaking things.

Summary & Practical Tip

Event hooks are your agent’s “auto-pilot” — they run at key moments to handle logging, alerts, or any custom logic you dream up. Start small: create a hook that logs agent:start and agent:end to a file. Once you see it working, expand to other events.

Pro tip: Use session:compress events to track when your agent’s context gets compacted. If you notice frequent compression, it’s a sign your conversations are getting too long — consider telling users to start fresh sessions more often.