hlothaire
hermes-trace
A Hermes Agent plugin that builds execution trace graphs using agent lifecycle hooks.
Repository last updated Jun 18, 2026
Overview
Hermes Trace is a plugin for the Hermes Agent ecosystem that provides deep visibility into agent execution by constructing structured trace graphs. It automatically captures every turn, LLM call, tool call, subagent spawn, and approval request using 18 lifecycle hooks, producing a directed graph of session activity.
Traces can be viewed interactively with the /trace slash command during a session or queried from the terminal using the hermes trace CLI. Output formats include JSON for machine processing, Mermaid diagrams for embedding in documentation, and text trees for human reading. An ASCII Gantt timeline helps analyze span concurrency and identify bottlenecks.
The plugin is designed for reliability: all hooks are wrapped in error-handling blocks so a single failure never orphans spans or crashes the agent. It requires no runtime dependencies beyond the Python standard library, making it lightweight and easy to deploy.
Highlights
- Captures 18 lifecycle hooks for comprehensive event tracing
- Exports traces as JSON, Mermaid diagrams, and text trees
- Includes ASCII Gantt timelines for analyzing span concurrency
- Zero runtime dependencies — pure Python stdlib
- Subagent linking with parent_trace field for bidirectional navigation
Features
Comprehensive Hook Coverage
18 lifecycle hooks automatically trace sessions, turns, API requests, tool calls, subagents, approvals, gateway dispatch, and result transformations.
Interactive and CLI Access
View traces via the <code>/trace</code> slash command in-session or use the <code>hermes trace</code> CLI for list, view, stats, gantt, and clean operations.
Multiple Output Formats
Traces are saved as JSON and Mermaid diagrams to <code>~/.hermes/traces/</code> at session end; text trees are rendered on demand.
Error Resilience
All hooks are wrapped in try/except blocks, ensuring a single broken callback never orphans spans or crashes the agent.
Subagent Linking
Child traces reference their parent session via a <code>parent_trace</code> field, enabling bidirectional navigation between related traces.
Installation
Commands are reproduced exactly as published by the project maintainers. Always check the upstream repository for the current instructions.
hermes plugins install hlothaire/hermes-trace
hermes plugins enable hermes-tracepip install hermes-tracehermes plugins enable hermes-tracegit clone https://github.com/hlothaire/hermes-trace
ln -s "$PWD/hermes-trace/hermes_trace" ~/.hermes/plugins/hermes-trace/
hermes plugins enable hermes-traceRequirements
- Python 3.12+
- Hermes Agent installed
How it's built
The plugin is written in Python and requires Python 3.12+. It has zero runtime dependencies, relying solely on the Python standard library. The repository is structured with the main plugin code in hermes_trace/, containing __init__.py for registration, tracer.py for the core TraceGraph, Span, Turn, and Subagent dataclasses, and cli.py for CLI handlers. The plugin.yaml manifest declares the 18 hooks.
Integration with Hermes Agent is automatic: the plugin registers its hooks, slash command, and CLI entry points via the register() function in __init__.py. Traces are stored as JSON and Mermaid files in ~/.hermes/traces/. The plugin can be installed via hermes plugins install hlothaire/hermes-trace, pip, or a manual symlink.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The hlothaire/hermes-trace repository is the authoritative source and the place to file issues or contribute.
Category: Observability & Telemetry · Licensed under MIT