Hermes Runtime Diagnostics

When the Hermes CLI itself is broken — commands produce no output, exit 0 with no diagnostic text, hang, or return empty — the problem is the runtime, not any config surface. This skill covers the diagnosis and recovery.

Resolve $HERMES_HOME first — every path below hangs off it: hermes config path prints the config file, its directory is the home (POSIX default ~/.hermes, native Windows %LOCALAPPDATA%\hermes). Named profiles re-home to <root>/profiles/<p>, and $HERMES_RUNTIME_DIR overrides tool paths — never hardcode ~/.hermes.

Symptoms

• hermes guide exits 0 but prints no scope output (just "finishing an interrupted source update" or nothing)
• hermes --version returns empty or hangs
• hermes doctor produces no output
• CLI commands hang indefinitely (exit 124 from timeout)
• Plugin load timeouts ("load timed out after 10s")

Step 1 — Confirm the scope, per probe

Run these in order; route on the FIRST one that misbehaves, not on the first that works:

hermes --version
hermes config path
hermes plugins list
hermes guide

• hermes config path hanging/empty → home unresolvable: fix that first (hermes-configuration-guide Step 0), then re-run the probes.
• hermes plugins list failing → Step 4 (plugin load health) directly.
• hermes --version empty/hanging → first check for a stuck source update / hermes-update.lock (Step 2 lock liveness); only if no lock is blocking, suspect the interpreter/venv/shim (see diagnosing-path), then continue with Step 5 (direct inspection) here — not Step 3.
• Version works but hermes guide prints nothing → stay here: the guide plugin itself fails to load — continue with Step 4 (plugin load health), not diagnosing-triage (triage's baseline needs a working guide).
• Version works and guide works → the runtime is fine; the issue is config-level (use diagnosing-triage instead).

Step 2 — Check for a stuck source update

The most common cause: an interrupted hermes update leaves the runtime in a degraded state where every CLI invocation tries to finish the update before doing anything else.

Symptoms: every command prints "finishing an interrupted source update..." and then either hangs or exits 0 with no real output.

Recovery:

# Retry the update
hermes update

If the wedge persists, the checkout lock or the owed completion tail is involved — do not invent lock filenames. The lock lives at <git common dir>/hermes-update.lock (or <install root>/.hermes-update.lock for a ZIP install), and an owed tail is recorded as a source-completion-pending marker. Follow the diagnosing-cli-tui stale-lock note for the liveness verdicts (live owner → wait; dead owner + free lock → human-confirmed removal; dead owner + held lock → wait, never delete) — including its no-baseline exception, since a fully wedged CLI cannot run any check first.

Step 3 — Check node dependencies (TUI/desktop scope only)

Node matters for the TUI (node-pty), the desktop app, and node-backed tools — not for the classic CLI, which is Python (hermes --version blank points at the interpreter/venv/shim per Step 1, never here). PM keeps one versioned directory per tool under $HERMES_HOME/tools/ named <tool>-<version>-<platform> — e.g. node-26.7.0-win32-x64 on this Windows host (darwin-arm64, linux-x64 triplets on theirs; list the directory to see yours, and note $HERMES_RUNTIME_DIR redirects the whole store) — plus a shared node/ tree — there is no tools/node symlink to repair, so never create one by hand.

# PM's view of the managed tools (repairs the recorded environment)
hermes pm doctor

# Reinstall a missing tool by package name
hermes pm install node

# Rebuild without re-resolving
hermes pm repair

Verify with hermes pm doctor (clean) and the previously failing surface (TUI launch, desktop start) — not by poking versioned directories directly.

Step 4 — Check plugin load health

If the CLI partially works but plugins fail:

# Check which plugins are enabled
python3 -c "import yaml; c=yaml.safe_load(open('config.yaml')); print(c.get('plugins',{}).get('enabled',[]))"

(run from the $HERMES_HOME resolved above — never a hardcoded home).

# Check plugin discovery
hermes plugins list 2>&1 | head -20

Plugins that time out during load (e.g. "load timed out after 10s") may indicate:

• A plugin with a broken import or missing dependency
• A plugin trying to connect to an external service during load
• Resource exhaustion (see diagnosing-host-pressure)

Temporary workaround: disable the failing plugin. For a regular plugin, comment it out of plugins.enabled in config.yaml:

plugins:
  enabled:
    # Remove or comment out the failing plugin
    # - some-regular-plugin

Then restart the session. Platform sub-plugins (telegram and friends) do NOT gate on plugins.enabled — check their selection key in config (see diagnosing-plugins) instead of editing the list.

Step 5 — Direct config inspection (bypass the CLI)

When the CLI is completely unusable, read config directly under the $HERMES_HOME resolved above:

# Config location
cat "$HERMES_HOME/config.yaml"

# Plugin directory
ls "$HERMES_HOME/plugins/"

# Skills directory
ls "$HERMES_HOME/skills/" | head -20

# Recent errors
cfg=$(hermes config path); d=$(dirname "$cfg"); tail -50 "$d/logs/errors.log"; tail -50 "$d/logs/agent.log"

This lets you diagnose config-level issues (wrong paths, missing files, syntax errors) without a working CLI.

Step 6 — Recovery escalation

If none of the above resolves the issue:

1. Restart the session — a fresh process may clear stuck state
2. Check for stale processes: ps aux | grep hermes — identify stray Hermes processes before killing any; never blanket-kill
3. As a last resort, reinstall Hermes — see installing-hermes

Step 7 — Delegate / swarm budgets

When a deep dive spawns subagents (delegate_task), keep the swarm cheap enough to keep the gateway loop responsive:

• Concurrency: keep delegations focused — roughly six children (tasks[]) and nesting depth of two. Hermes enforces the configured delegation.max_concurrent_children and delegation.max_spawn_depth values; the caps above are recommendations to finish sooner and expose the gateway to fewer polls, not hard limits. In Hermes v0.22.5 the default depth limit is one, so children cannot delegate unless delegation.max_spawn_depth is configured higher. In one-shot sessions, delegation.oneshot_max_children also limits the total children per session (default two; zero means unlimited).
• Poll cadence: while busy, the TUI monitor polls subagent.list at most once a second. A dead connection surfaces first as ws response send failed … method=subagent.list — see diagnosing-gateway §3b; hermes guide gateway reports the disconnect and message count.
• Timeout budget: a 990s timeout was observed on the installed Hermes (2026-11-06), but the pinned Hermes has no child-timeout default — an optional configured timeout is an inactivity cap. Diagnose a timed-out delegate by checking child progress (last API call / tool) and the configured timeout, not a presumed default. Prefer explicit, short budgets per task and re-run with narrower goal/context instead of raising the deadline.
• Context budget: keep per-turn input tokens small. Large inputs lengthen child work and provider cost, and align (by correlation only) with keepalive pressure (see diagnosing-gateway §3b); never attribute a disconnect to context size without independent stall evidence. Pass file paths, not file contents, in context; let the child read what it needs.
• Swarm shape: split by surface (project core, probe/tests, PR diff, skill mapping), each child self-contained — the child knows nothing of the parent conversation. After all children return, the parent synthesizes; children return findings only and never mutate.

When to use this vs other skills

• This skill: CLI produces no output, commands hang, runtime is broken
• diagnosing-triage: CLI works, but something is misconfigured
• diagnosing-desktop: Desktop app specifically won't launch
• diagnosing-plugins: A specific plugin won't load (but CLI works)
• installing-hermes: Fresh install or complete reinstall needed

Verification

After applying fixes:

# Re-run the Step 1 probes in order
hermes --version
hermes config path
hermes plugins list
hermes guide

# If node/TUI was the issue
hermes pm doctor

# Check for new errors (resolve active home via hermes config path)
# Record before the fix: baseline=$(wc -l < "$(dirname "$(hermes config path)")/logs/errors.log")
cfg=$(hermes config path); tail -n +"$((baseline + 1))" "$(dirname "$cfg")/logs/errors.log" | grep -n "load timed out" || true

Expected: hermes --version prints a version string; hermes guide prints scope output with no timeouts; hermes pm doctor exits clean; no new load timed out lines in errors.log.

Report

This skill diagnoses Hermes runtime failures — commands producing no output, exit 0 with no text, hangs, or empty results. Apply this report based on Step 1 probe results:

• CLI-wide failure (hermes --version hangs/empty): first check for a stuck source update / hermes-update.lock — a stale lock blocks every command. Only treat as runtime/venv/shim if no lock is present. Focus on Steps 2, 5-6 (updates, PM tools, direct inspection); check Step 3 (node dependencies) only when a TUI or desktop probe fails.
• CLI works but hermes guide prints nothing: treat as plugin load failure (Step 4). Do not assume the whole CLI is broken.

Summary

Adjust to match the probe: for CLI-wide failure, state the interpreter/venv/runtime is non-functional; for guide-only failure, state the guide plugin failed to load while the CLI is usable.

Findings

Recommended Fix

1. If CLI-wide broken: Check for stuck updates (hermes update, inspect <git common dir>/hermes-update.lock, or <install root>/.hermes-update.lock for a ZIP install without .git). Follow liveness checks per diagnosing-cli-tui. Verify runtime deps with hermes pm doctor if needed. Inspect config/logs directly under $HERMES_HOME if CLI unusable; escalate to installing-hermes as last resort.
2. If guide-only broken: Follow Step 4 (plugin load health) - check hermes plugins list, logs for timeouts/import errors. Disable failing plugin if needed (hermes plugins disable <name>), restart session. See diagnosing-plugins.

References

• $HERMES_HOME/config.yaml and logs ($HERMES_HOME/logs/)
• hermes_cli/update_lock.py, hermes_cli/venv_sync.py
• diagnosing-cli-tui (stale lock handling)
• diagnosing-path (interpreter/venv resolution)
• diagnosing-plugins (plugin load issues)

Facts re-verified 2026-11-06 against the installed Hermes (v0.22.5, delegate_task 6-child / depth-2 limits, subagent.list once-a-second poll, 990s delegate deadline; see diagnosing-gateway §3b) and this repo's check_gateway_health; upstream source at 9bda154d (v0.21.7) verified 2026-10-16: PM-versioned tool layout; owed-tail marker source-completion-pending; checkout lock names; platform selection keys over plugins.enabled. Re-verify before reuse.