hermes-labyrinth-observability

Q: How do I install hermes-labyrinth-observability?

Run npx skills add https://github.com/reason-machines/hermes-skills --skill hermes-labyrinth-observability in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hermes-labyrinth-observability/ (personal) or .claude/skills/hermes-labyrinth-observability/ (project).

by reason-machinesDevOps & Cloud

Hermes Labyrinth observability plugin for monitoring autonomous agent journeys, crossings, and execution traces

Installs: 150
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/hermes-skills --skill hermes-labyrinth-observability

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads hermes-labyrinth-observability automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Hermes Labyrinth Observability Plugin

Skill by ara.so — Hermes Skills collection.

Hermes Labyrinth is a read-only observability plugin for Hermes Agent that provides detailed monitoring of autonomous agent execution. It visualizes agent "journeys" as sequences of "crossings" (prompts, tool calls, results, failures, model switches, subagents) and generates exportable reports with built-in secret redaction.

Installation

Install into the Hermes user plugin directory:

mkdir -p ~/.hermes/plugins
git clone https://github.com/stainlu/hermes-labyrinth.git ~/.hermes/plugins/hermes-labyrinth

After installation, restart the Hermes dashboard:

hermes dashboard

The Labyrinth tab will appear in the dashboard UI at http://127.0.0.1:9119.

Docker Installation

For Docker-based Hermes installations, mount the plugin directory:

mkdir -p ~/.hermes/plugins
git clone https://github.com/stainlu/hermes-labyrinth.git ~/.hermes/plugins/hermes-labyrinth
cd ~/.hermes/plugins/hermes-labyrinth
git checkout v0.1.3  # Pin to reviewed version

Mount the Hermes home directory into your container and restart the dashboard.

Plugin Management

Rescan Plugins (Frontend Only)

Refresh discovered frontend manifests without full restart:

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

Note: Backend API changes require a full dashboard restart.

Disable/Remove Plugin

hermes plugins disable hermes-labyrinth
rm -rf ~/.hermes/plugins/hermes-labyrinth
curl http://127.0.0.1:9119/api/dashboard/plugins/rescan

API Reference

All endpoints are read-only and include automatic secret redaction.

Health Check

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/health

Returns plugin status and Hermes state accessibility.

List Journeys

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys

Returns recent CLI, dashboard, gateway, cron, and delegated agent sessions.

Get Journey Details

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys/{journey_id}

Returns metadata for a specific journey including start time, status, and model usage.

Get Journey Crossings

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys/{journey_id}/crossings

Returns ordered sequence of crossings (messages, tool calls, results) for a journey.

Get Skills Inventory

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/skills

Returns:

skills: effective skills loaded
shadowed: expected user-over-bundled overrides
duplicates: true duplicate diagnostics
errors: skill scan errors

Get Cron Configuration

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/cron

Returns scheduled autonomy jobs, next run times, last failures, and working directories.

Get Guideposts

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/guideposts

Returns generated observations backed by local evidence across journeys.

Export Reports

JSON format:

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.json > journey.json

Markdown format:

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.md > journey.md

Both formats include automatic secret redaction.

Python Plugin API Extension

Hermes Labyrinth extends the dashboard with custom backend routes. The core implementation is in dashboard/plugin_api.py.

Example: Custom API Route

from fastapi import APIRouter, HTTPException
from typing import Dict, Any
import os

router = APIRouter(prefix="/api/plugins/hermes-labyrinth")

@router.get("/custom-endpoint")
async def custom_endpoint() -> Dict[str, Any]:
    """Example custom endpoint for plugin."""
    hermes_home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
    
    # Read-only access to Hermes state
    state_db = os.path.join(hermes_home, "state.db")
    
    if not os.path.exists(state_db):
        raise HTTPException(status_code=503, detail="Hermes state unavailable")
    
    return {
        "status": "ok",
        "hermes_home": hermes_home
    }

Accessing Hermes State

The plugin reads from:

~/.hermes/state.db: Sessions and messages (SQLite)
~/.hermes/skills/: User and bundled skills
~/.hermes/cron/: Scheduled job configurations

import sqlite3
import os

def query_journeys(hermes_home: str):
    """Query recent sessions from Hermes state.db"""
    state_db = os.path.join(hermes_home, "state.db")
    
    conn = sqlite3.connect(state_db)
    conn.row_factory = sqlite3.Row
    
    cursor = conn.cursor()
    cursor.execute("""
        SELECT session_id, created_at, updated_at, status, model
        FROM sessions
        ORDER BY updated_at DESC
        LIMIT 100
    """)
    
    sessions = [dict(row) for row in cursor.fetchall()]
    conn.close()
    
    return sessions

Frontend Development

The dashboard UI is built from modular JavaScript components.

Build Process

npm run build

Generates:

dashboard/dist/labyrinth-bundle.js: Combined JS from src/parts/*.js
dashboard/dist/labyrinth.css: Copied from src/labyrinth.css
index.html: GitHub Pages demo with content hashes

Development Workflow

# Build and verify
npm run build
npm run check

# Run smoke tests
npm run smoke

# Test live demo
npm run smoke:live

Frontend Structure

// src/parts/01-state.js - Global state management
const LabyrinthState = {
  journeys: [],
  selectedJourney: null,
  crossings: [],
  mode: 'chronological'
};

// src/parts/02-api.js - API client
async function fetchJourneys() {
  const response = await fetch('/api/plugins/hermes-labyrinth/journeys');
  return response.json();
}

// src/parts/03-components.js - UI components
function renderJourneyCard(journey) {
  return `
    <div class="journey-card" data-id="${journey.id}">
      <h3>${escapeHtml(journey.title)}</h3>
      <time>${new Date(journey.created_at * 1000).toLocaleString()}</time>
    </div>
  `;
}

Configuration

Optional Theme

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

Plugin Manifest

Located at dashboard/manifest.json:

{
  "name": "hermes-labyrinth",
  "version": "0.1.3",
  "title": "Labyrinth",
  "description": "Agent journey observability",
  "entry_js": "dist/labyrinth-bundle.js",
  "entry_css": "dist/labyrinth.css",
  "api_module": "plugin_api"
}

Common Patterns

Filtering Journeys by Status

# Get all journeys and filter with jq
curl -s http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys | \
  jq '.journeys[] | select(.status == "completed")'

Analyzing Tool Call Patterns

# Get crossings and count tool types
curl -s http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys/{journey_id}/crossings | \
  jq '.crossings[] | select(.type == "tool_call") | .tool_name' | \
  sort | uniq -c

Exporting Multiple Journeys

# Export last 10 journeys as JSON
curl -s http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys | \
  jq -r '.journeys[].id' | head -10 | while read id; do
    curl -s "http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/$id.json" > "journey_$id.json"
  done

Monitoring Agent Failures

# List failed journeys with error details
curl -s http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys | \
  jq '.journeys[] | select(.status == "failed") | {id, error, updated_at}'

Security and Redaction

Labyrinth applies Hermes core secret redaction to all outputs:

from hermes.redactor import redact_secrets

def safe_export(content: str) -> str:
    """Apply redaction before export."""
    try:
        return redact_secrets(content)
    except Exception:
        # Fail closed if redactor unavailable
        return "[redaction unavailable]"

Verification Before Production

Test redaction with dummy secrets:

# Create test journey with dummy API keys in prompts/outputs
hermes chat "Test: sk-dummy-key-12345"

# Verify redaction in UI and exports
curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.json | grep "sk-dummy"
# Should return nothing if redaction works

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.md | grep "sk-dummy"
# Should return nothing if redaction works

Testing

Run Full Test Suite

npm test

Includes:

Build reproducibility checks
JavaScript/Python parse validation
API normalization fixture tests
Headless Chrome smoke tests

Backend API Tests

python3 scripts/test-plugin-api.py

Tests timestamp normalization, redaction, and data structure handling.

Manual Smoke Test

npm run smoke

Runs headless Chrome against built demo:

Map mode switching
Route navigation
Search functionality
Dataset switching
Threshold filtering

Troubleshooting

Plugin Not Appearing in Dashboard

Verify installation path:

ls -la ~/.hermes/plugins/hermes-labyrinth/dashboard/manifest.json

Restart dashboard (rescan doesn't mount new Python routes):

# Stop dashboard
hermes dashboard stop

# Start dashboard
hermes dashboard

Check dashboard logs for plugin API import errors.

Backend/API Diagnostic in UI

This means the Python API routes failed to load:

Restart dashboard completely (not just rescan)
Check Python imports:

python3 -c "import sys; sys.path.insert(0, '$HOME/.hermes/plugins/hermes-labyrinth/dashboard'); import plugin_api"

Verify Hermes home exists:

ls -la ~/.hermes/state.db

Redaction Unavailable Error

If reports show [redaction unavailable]:

Verify Hermes core is installed properly
Check redactor import:

from hermes.redactor import redact_secrets

This is a fail-closed safety mechanism — plugin won't export unredacted content

Empty Journeys List

Verify agent sessions exist:

sqlite3 ~/.hermes/state.db "SELECT COUNT(*) FROM sessions;"

Check file permissions:

ls -la ~/.hermes/state.db

Run health check:

curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/health

Build Failures

# Clean and rebuild
rm -rf dashboard/dist index.html
npm run build
npm run check

Development References

Live demo: https://stainlu.github.io/hermes-labyrinth/
Hermes Agent: https://github.com/NousResearch/hermes-agent
Plugin docs: docs/CONCEPT.md, docs/DESIGN_BRIEF.md, docs/FUNCTIONAL_SPEC.md
License: MIT

FAQ

What does the hermes-labyrinth-observability skill do?

Hermes Labyrinth observability plugin for monitoring autonomous agent journeys, crossings, and execution traces

How do I install hermes-labyrinth-observability?

Run npx skills add https://github.com/reason-machines/hermes-skills --skill hermes-labyrinth-observability in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hermes-labyrinth-observability/ (personal) or .claude/skills/hermes-labyrinth-observability/ (project).

Which AI agents can use hermes-labyrinth-observability?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is hermes-labyrinth-observability safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains hermes-labyrinth-observability?

It is published by reason-machines in reason-machines/hermes-skills. It has 150 recorded installs.

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

hermes-labyrinth-observability

Install

Install

Describe the task

Review the result

SKILL.md

Hermes Labyrinth Observability Plugin

Installation

Docker Installation

Plugin Management

Rescan Plugins (Frontend Only)

Disable/Remove Plugin

API Reference

Health Check

List Journeys

Get Journey Details

Get Journey Crossings

Get Skills Inventory

Get Cron Configuration

Get Guideposts

Export Reports

Python Plugin API Extension

Example: Custom API Route

Accessing Hermes State

Frontend Development

Build Process

Development Workflow

Frontend Structure

Configuration

Optional Theme

Plugin Manifest

Common Patterns

Filtering Journeys by Status

Analyzing Tool Call Patterns

Exporting Multiple Journeys

Monitoring Agent Failures

Security and Redaction

Verification Before Production

Testing

Run Full Test Suite

Backend API Tests

Manual Smoke Test

Troubleshooting

Plugin Not Appearing in Dashboard

Backend/API Diagnostic in UI

Redaction Unavailable Error

Empty Journeys List

Build Failures

Development References

FAQ

More from reason-machines/hermes-skills

Popular devops & cloud skills