Hermes Health Check

Hermes Health Check

Run Hermes' own read-only diagnostics, then turn what they print into a short list of problems, each with the exact fix.

When to Use

• The user says Hermes, the gateway, cron, or a platform "isn't working".
• After hermes update, to confirm everything came back.
• As a daily cron job on an always-on host.

Procedure

Run every command with the terminal tool. This skill only reads. See the pitfalls before suggesting any fix that writes.

1. Version and pending updates:

   bashCopy code
   hermes --version
   hermes update --check
   

2. Hermes' own diagnostics (read-only; never add --fix from inside a session):

   bashCopy code
   hermes doctor
   hermes status
   hermes config check
   

3. Gateway and cron:

   bashCopy code
   hermes gateway status
   hermes cron status
   hermes cron list
   

   Cron fires only while a gateway runs. If hermes cron status warns that the gateway runs stale code, the fix is a gateway restart.

4. Recent errors:

   bashCopy code
   hermes logs errors --since 24h
   hermes logs gateway --since 24h --level WARNING
   

5. Map each finding to a fix. The most common ones:

   Finding	Fix
   No gateway running, so cron won't fire	hermes gateway start, or hermes gateway install if no service exists. Never add a system unit next to an existing user service: remove one first (hermes gateway uninstall).
   Both a user and a system gateway service installed	Two services fight over the same bot tokens. Keep one and uninstall the other.
   Gateway on stale code after an update	hermes gateway restart
   Missing or outdated options	hermes config check, then hermes config migrate
   "not a recognized config key"	Check the key name for a typo. v0.21.4 also prints this for some real keys (agent.reasoning_effort, model_aliases.*, skills.creation_nudge_interval), and for those it's harmless.
   A platform's bot doesn't answer	Check that platform's allowlist or run hermes pairing list. Discord needs the Message Content intent.
   "another Hermes process still holds an old copy of the session database's write-ahead log"	Stop every Hermes process, run hermes doctor until no holder is listed, then start one process
   Version older than 0.21.2	Update. That release fixed a class of session-database corruption.

6. Report: one line of overall status, then the problems ordered by severity, each with its fix command and whether the user must run it (anything that restarts or rewrites something).

Verification

• hermes doctor shows no errors after the fixes are applied.
• hermes gateway status shows the gateway running, and hermes cron status shows the scheduler active.

Pitfalls

• Never run hermes doctor --fix, hermes sessions optimize, hermes sessions optimize-storage, or hermes sessions prune from inside an agent session. This session itself holds the session database, and those commands rewrite it. Hand them to the user to run with every Hermes process stopped.
• Never delete state.db-wal or state.db-shm. They contain committed conversations.
• If this session runs through the gateway (for example in a Telegram chat), hermes gateway restart restarts the process answering the user. Warn them first, or let them run it.
• hermes doctor --live makes real network calls to tool backends. Only use it when the user asks.