stainlu
hermes-labyrinth
Read-only observability plugin for Hermes Agent: journeys, crossings, guideposts, and reports.
Repository last updated May 4, 2026
Overview
Hermes Labyrinth is a read-only observability plugin for Hermes Agent that transforms autonomous agent workflows into a structured map of events. It acts as a black-box recorder, reading local state to track prompts, tool calls, model transitions, and subagent activities without mutating session data. The plugin provides deep diagnostic visibility through specialized views for skill overrides, scheduled cron tasks, and redacted journey reports.
Users can export evidence in Markdown or JSON formats while relying on built-in redaction to protect sensitive credentials. The plugin is designed for developers and operators who need to inspect agent behavior, debug issues, or audit autonomous operations without interfering with the agent's runtime.
Hermes Labyrinth is not a chat UI; it is a diagnostic tool that visualizes the internal workings of Hermes Agent sessions. It integrates as a dashboard tab and exposes a set of read-only API endpoints for querying journey data, crossings, skills, cron schedules, and guideposts.
Highlights
- Visualizes agent journeys through ordered crossings and event maps
- Provides diagnostic views for skill overrides and cron schedules
- Generates redacted Markdown and JSON reports for session evidence
- Read-only design ensures no mutation of agent state
- Built-in secret redaction with fail-closed behavior
Features
Journey Index
Lists recent CLI, dashboard, gateway, cron, and delegated work sessions.
Labyrinth Map
Displays ordered crossings through a selected agent journey.
Inspector
Shows input, output, duration, status, evidence, and guideposts for a selected crossing.
Guideposts
Generated observations backed by local evidence for each crossing.
Skill Atlas
Lists effective skills along with shadowed overrides and true duplicate diagnostics.
Cron Gate
Displays scheduled autonomy, next runs, last failures, and work directories.
Model Ferry
Tracks model/provider transitions across sessions.
Reports
Exports redacted Markdown and JSON summaries for a single journey.
Installation
Commands are reproduced exactly as published by the project maintainers. Always check the upstream repository for the current instructions.
mkdir -p ~/.hermes/plugins
git clone https://github.com/stainlu/hermes-labyrinth.git ~/.hermes/plugins/hermes-labyrinthhermes dashboardcurl http://127.0.0.1:9119/api/dashboard/plugins/rescanmkdir -p ~/.hermes/dashboard-themes
cp ~/.hermes/plugins/hermes-labyrinth/theme/hermes-labyrinth.yaml ~/.hermes/dashboard-themes/Requirements
- Hermes Agent installed and running
- Hermes dashboard accessible (typically on localhost:9119)
- Node.js (for building from source, optional if using pre-built dist)
- Git (for cloning the repository)
How it's built
Hermes Labyrinth is built as a Hermes dashboard plugin. The backend is implemented in Python (dashboard/plugin_api.py) and exposes a set of read-only API endpoints under /api/plugins/hermes-labyrinth/. The frontend is a single-page application built from modular JavaScript parts (src/parts/*.js) and CSS (src/labyrinth.css), bundled into dashboard/dist/ via a build script.
The plugin reads local Hermes state from state.db (sessions/messages), skills directories, and cron configuration. It does not write to any state. Secret redaction is applied to journey summaries and reports; if the Hermes core redactor fails, the plugin shows [redaction unavailable] instead of raw trace text.
The repository layout includes a dashboard/ directory with the plugin manifest and API, a src/ directory with frontend source, a docs/ directory with design documents, and a theme/ directory with an optional YAML theme scaffold. The plugin is installed by cloning into the Hermes user plugin directory (~/.hermes/plugins/hermes-labyrinth) and requires a dashboard restart after first install or API updates.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The stainlu/hermes-labyrinth repository is the authoritative source and the place to file issues or contribute.
Category: Observability & Telemetry · Licensed under MIT