Hermes Guide

Package / slug: hermes-guide · Catalog: curated Hermes plugin catalog (community tier)

Hermes usage and self-diagnosis guide for Hermes Agent.
It is an independent community project: not a Hermes core component, and it does
not ask upstream to change for this plugin's benefit. Genuine Hermes defects
found during diagnosis may still be reported upstream.

It complements — never replaces — Hermes's own diagnostics (hermes doctor, hermes verify, and the per-surface helpers): it covers the gaps they leave. The plugin is read-only (no config writes; empty capabilities:). It ships two independent things:

1. A plugin. /hermes-doctor in a session, hermes guide in a terminal. Read-only health checks across
   config, mcp, skills, commands, hooks, plugins, memories, sessions, storage, update

1. A skills tap.
   Thirty-one troubleshooting skills — one install guide, one configuration map, twenty-seven per-surface diagnosing-* playbooks, two other skills (hermes-post-update, plugin-authoring).

Enabling the plugin additionally registers one router skill (hermes-guide:start) in
model sessions: it routes "something is wrong" reports to hermes guide and, once
the tap is installed, to the matching playbook. The playbooks themselves ship only
via the tap.

Who it's for. A session helping someone who does not read Hermes's source: the
plugin gives it a deterministic picture of the host, the tap gives it the per-surface
playbook, and each finding gives a reason and, where the check has one, the path or
output behind it. That is what lets a problem be triaged before an upstream fix
lands — and what lets an upstream maintainer act on a report without re-deriving
the user's environment. Read-only throughout: no config writes, no auto-fix.

[!NOTE]
The hooks check inspects hook configuration in-process by default — it
reads the config, consent state and exec bit without running anything. Add
--deep to run hermes hooks doctor, which executes each approved shell
hook once with a synthetic payload; that is how it verifies a hook actually
runs. Proactive runs always stay in-process.

Install the plugin

From the curated catalog (preferred):

hermes plugins install hermes-guide
hermes plugins enable hermes-guide

Catalog installs land disabled — the enable step is what registers
/hermes-doctor and hermes guide. (Owner/repo installs pass --enable
inline instead.)

From GitHub by owner/repo (same package; useful to pin a SHA):

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

Requires Hermes >=0.21 — declared as requires_hermes in plugin.yaml and
enforced by the plugin loader (a build without it records-and-skips at load).
See hermes plugins info hermes-guide for the
catalog pin and disclosure text.

Manual install

Alternatively, clone this repo 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 adopt hermes-guide
hermes plugins enable hermes-guide

Adopting registers the self-cloned directory in provenance tracking so
hermes plugins update covers it. Prefer a fresh clone over cp -r .: it leaves working-tree caches and build
artifacts (__pycache__, venvs) behind. Keep the clone's .git — Hermes
updates Git-managed plugins in place, and deleting it breaks those updates.
Only delete .git for a standalone archive copy that will never be updated
as a plugin.

[!NOTE]
On native Windows $HERMES_HOME is %LOCALAPPDATA%\hermes, not ~/.hermes. Run hermes config path to confirm where yours is.

Use the plugin

• In a session: /hermes-doctor for every surface, or /hermes-doctor mcp for one.
• In a terminal: hermes guide. Exits 1 if any surface is broken or unknown, 2 for an unrecognized scope name, 0 when healthy. On a degraded host — where every hermes launch replays a minutes-long update tail — hermes guide --fast runs all ten checks in-process with no subprocess.
• Deep hooks: hermes guide hooks --deep (or /hermes-doctor hooks --deep) runs hermes hooks doctor, which executes each approved hook once. The default hooks check runs nothing.
• Machine-readable: hermes guide mcp --json prints one JSON document instead of the report — envelopes unchanged, top-level status derived, update notice suppressed (exit codes above still apply). Agents and scripts parse that document; plain grep-style consumers keep the text output.
• Finding ids: every broken or unknown result carries a stable id, impact, and fix; the finding catalog lists scope separately, and --json emits those keys in each finding envelope under its scope key.

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

Installing the plugin does not install the skills; they ship as separate, opt-in reference material. Add the repo as a skills tap, then install what you want:

hermes skills tap add iap/hermes-guide
hermes skills install iap/hermes-guide/skills/diagnosing-mcp

[!IMPORTANT]
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-auth diagnosing-backup diagnosing-bot-mode diagnosing-browser diagnosing-cli-tui diagnosing-commands diagnosing-config diagnosing-cron diagnosing-desktop diagnosing-gateway diagnosing-hooks diagnosing-host-pressure diagnosing-mcp diagnosing-memories diagnosing-memory diagnosing-path diagnosing-plugins diagnosing-profiles diagnosing-providers diagnosing-runtime diagnosing-secrets diagnosing-sessions diagnosing-skills diagnosing-storage diagnosing-triage diagnosing-update diagnosing-voice hermes-configuration-guide hermes-post-update installing-hermes plugin-authoring; do hermes skills install "iap/hermes-guide/skills/$s"; done

Each skill still passes its own scan and consent individually, so it stays individually updatable. Every installed skill is also available as a slash command (e.g. /diagnosing-mcp).

What's included

Design principle

Complement, don't duplicate. When a built-in already answers the question, use it — hermes-guide exists for the gaps: deep per-surface 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.

Machine-readable diagnostics

Phase 4 shipped the machine-readable contract. hermes guide --json emits one
document per run, every broken or unknown finding carries a stable id with
plain-language impact and a concrete fix, and the
finding catalog is generated from that registry. The triage
and router skills consume the contract. Runtime repair stays
upstream with hermes doctor --fix; hermes doctor --live only runs bounded,
read-only health probes.

No next phase is scoped yet; open
issues carry the work.

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.