The Problem

Hermes Agent produces large volumes of session, tool-call, and approval state. Operators lack a read-only way to orient inside that activity without modifying agent state or exposing secrets. hermes-labyrinth is a dashboard plugin that normalizes that state into navigable views—journeys, crossings, guideposts, and skill inventories—so a human can inspect what the agent did and why.

What This Does

The plugin is a read-only extension for the Hermes dashboard. It consumes Hermes state and exposes structured views: journeys (sessions, cron runs, delegated work), crossings (prompts, tool calls, approvals), guideposts (explainable observations), a skill atlas, a cron gate, and redacted Markdown reports. The visual layer is intentionally minimal; the product behavior is ready for a designer to shape.

The implementation is split between a Python backend (dashboard/plugin_api.py, 601 lines) and a compiled React frontend (dashboard/dist/index.js). Documentation lives in docs/ (concept, functional spec, design brief). A theme scaffold is provided in theme/hermes-labyrinth.yaml.

How It Is Wired

Execution starts at the dashboard plugin entry point: dashboard/plugin_api.py. The plugin is auto-discovered because the repo lives under plugins/. The Python module exposes the API that the React frontend (dashboard/dist/index.js) calls. The frontend is pre-built; there is no build step in this repo.

The measured import graph shows one internal module (dashboard/plugin_api) with zero import edges—the plugin is self-contained and does not depend on other modules in this repo. It interacts with the outside world via the Hermes dashboard API and local state files. The blast radius is concentrated in plugin_api.py: it owns all backend behavior, and at 601 lines, a change there can ripple across every dashboard view.

File-by-file map:

  • dashboard/plugin_api.py — backend API; all data normalization and report generation.
  • dashboard/dist/index.js — compiled React frontend; renders all dashboard views.
  • dashboard/dist/labyrinth.css — styling.
  • dashboard/manifest.json — plugin metadata for Hermes discovery.
  • theme/hermes-labyrinth.yaml — theme scaffold.
  • docs/ — concept, functional spec, design brief.
  • index.html and Hermes Labyrinth _standalone_.html — standalone previews.

The wiring beyond the plugin boundary (how Hermes invokes plugin_api.py, which endpoints the frontend calls) has not been mapped by this analysis.

How To Use It

Setup: Copy the theme scaffold into the Hermes dashboard themes directory, as documented in the README:

mkdir -p ~/.hermes/dashboard-themes
cp plugins/hermes-labyrinth/theme/hermes-labyrinth.yaml ~/.hermes/dashboard-themes/

Running it: Restart hermes dashboard, or trigger a plugin rescan:

curl http://127.0.0.1:9119/api/dashboard/plugins/rescan

Then open the dashboard and select the Labyrinth tab. No build step is required; dashboard/dist/index.js is pre-compiled.

Configuration: No environment variables or config files are documented. The plugin is read-only and applies secret redaction to previews and reports.

Real-World Use

An operator debugging an unexpected agent run opens the Hermes dashboard, selects the Labyrinth tab, and inspects the crossings for that session. They see each tool call, its result, and the model/context transitions. A guidepost flags an anomaly backed by local evidence. They export a redacted report in Markdown and attach it to a ticket—without ever modifying Hermes state.

Code Health & Issues

Static analysis found 3 medium findings, all in dashboard/plugin_api.py:

  • Medium (resilience) — Broad exception handling: bare or Exception-wide except swallows errors indiscriminately. Fix: catch specific exceptions; re-raise or log the rest.
  • Medium (cognitive load) — Deep nesting: max indentation depth 7 makes control flow hard to follow. Fix: early returns, guard clauses, extract inner blocks.
  • Medium (cognitive load) — Oversized file: 601 code lines; a change here ripples widely. Fix: split into cohesive units by responsibility.

SDLC observations from the file structure: no CI/CD pipeline detected (no .github/ or CI config), no LICENSE file, no Dockerfile, and no lockfile. One test file exists, but the analysis did not confirm what it covers.

The Bottom Line

A clean, self-contained dashboard plugin that solves a real observability gap for Hermes operators. The Python backend is the main maintenance risk—overly broad exception handling and deep nesting will make changes harder than they need to be. Worth adopting if you run Hermes and need a read-only orientation layer; add CI and a license before sharing it broadly.