Hermes Guide

Package / slug: hermes-guide

Hermes usage and self-diagnosis guide for Hermes Agent. It complements — not replaces — Hermes's built-in diagnostics (hermes doctor, hermes verify, and the platform helpers): it is an extra layer covering what they don't. It ships two things:

1. A plugin — /hermes-doctor (in-session) and hermes guide (terminal): read-only diagnostics across config, mcp, skills, commands, hooks, plugins, and memories — each name is a valid scope.
2. Twelve troubleshooting skills — teach an agent how to locate and fix each surface, plus install, venv, auth, memory, and desktop guides.

Install the plugin

hermes plugins install iap/hermes-guide --enable

This clones the repo from GitHub and enables it. To pin an immutable commit:

hermes plugins install iap/hermes-guide --ref <40-char-SHA> --enable

Manual install

Alternatively, clone this repo directly into your Hermes plugins directory:

# POSIX / WSL: $HERMES_HOME is ~/.hermes
git clone --depth 1 https://github.com/iap/hermes-guide ~/.hermes/plugins/hermes-guide
hermes plugins enable hermes-guide

A clone (rather than cp -r .) keeps VCS metadata and local caches out of the plugin directory. On native Windows $HERMES_HOME is %LOCALAPPDATA%\hermes (not ~/.hermes); run hermes config path to confirm.

Usage

• In a session: /hermes-doctor (all surfaces) or /hermes-doctor mcp (one surface).
• In a terminal: hermes guide — exits 1 if any surface is broken or unknown (indeterminate), and 2 for an unrecognized scope name.

Proactive mode (opt-in)

Add to config.yaml:

plugins:
  entries:
    hermes-guide:
      settings:
        proactive: true

Drift findings are then logged at session start/end — watch hermes logs --follow.

Install the skills (tap)

Installing the plugin (above) does not list or install the skills — they ship as separate, opt-in reference material. To make them appear under hermes skills, add this repo as a skills tap, then install what you want:

hermes skills tap add iap/hermes-guide
hermes skills install iap/hermes-guide/skills/hermes-configuration-guide

The other eleven skills use the same iap/hermes-guide/skills/<name> form: installing-hermes, diagnosing-mcp, diagnosing-skills, diagnosing-commands, diagnosing-hooks, diagnosing-plugins, diagnosing-path, diagnosing-cli-tui, diagnosing-auth, diagnosing-memory, diagnosing-desktop.

Note

The identifier must include the skills/ prefix (it is the repo-relative path to the skill's SKILL.md). The shorter iap/hermes-guide/<name> form does not resolve.

Install all skills at once

for s in diagnosing-mcp diagnosing-skills diagnosing-commands diagnosing-hooks diagnosing-plugins diagnosing-path diagnosing-cli-tui diagnosing-auth diagnosing-memory diagnosing-desktop installing-hermes hermes-configuration-guide; do hermes skills install "iap/hermes-guide/skills/$s"; done

Each skill still passes its own scan + consent individually (scanner-honest, individually updatable).

Each installed skill is also available as a slash command (e.g. /hermes-configuration-guide).

What's included

Skill	Purpose
installing-hermes	Install routes — install.sh/Desktop/Nix/PyPI, what each creates on disk, config bootstrap, update/uninstall, and the gotchas (npm postinstall hang, NixOS specifics)
hermes-configuration-guide	The map: resolving $HERMES_HOME, where each surface is configured, instruction files, orphaned/legacy settings, and routing to the diagnostic skills
diagnosing-mcp	MCP servers that won't connect, expose no tools, fail OAuth, or ignore mcp_servers: config
diagnosing-skills	Skills not discovered, shadowed, hidden by platform/toolset conditions, or stuck "user-modified"
diagnosing-commands	Missing or overridden slash commands — skills-as-commands, bundles, plugin commands, per-platform permissions
diagnosing-hooks	Hooks that don't fire — the four hook systems, shell-hook consent, hermes hooks doctor
diagnosing-plugins	Plugins that don't load — the plugins.enabled gate, capability consent, discovery locations
diagnosing-path	Path issues — the dual-venv layout (.venv/venv), detection, canonical resolution order, cross-platform best practices
diagnosing-cli-tui	CLI/TUI issues on native Windows — rendering artifacts, themes, busy indicators, mouse modes, encoding, launch/resume
diagnosing-auth	Hub-install auth failures — dead/shadowing GITHUB_TOKEN in the profile .env, gh-cli fallback, 401 vs anonymous probes, rate-limit verdicts
diagnosing-memory	Memory problems — built-in MEMORY.md/USER.md stores, external providers configured but silently unavailable, missing plugins/keys, char-limit and approval gates
diagnosing-desktop	Desktop app build/launch failures — npm/Node issues, locked or torn builds, Electron download fallbacks, backend resolution, desktop.* config

Design principle

Complement, don't duplicate. When a built-in (hermes doctor, hermes verify, per-surface helpers) already answers the question, use it — hermes-guide exists for the gaps: deep per-surface troubleshooting playbooks, deterministic read-only health checks, and the routing map between surfaces. If a check here ever starts duplicating a built-in, the built-in wins and the check gets trimmed.

Every diagnosis resolves to a concrete action: a hermes <subcommand> command or a specific file + field edit, then a /reload-* or restart to apply.

Contributing

Skills track the Hermes Agent source and its shipped documentation (website/docs/ in hermes-agent). When Hermes changes behavior, update the affected skill and bump its version. See CONTRIBUTING.md.

License

MIT — see LICENSE.