Hermes Agent System Doctor: developer tool for Hermes Agent

Read-only diagnostics and approval-gated repair planning for local Hermes Agent installations

What Hermes Agent System Doctor does

Stock hermes doctor checks the base install. This tool maps the wider local system: root and named profiles, config.yaml parseability, gateway config, log and PID signals, cron metadata, logs by category, auth and secret-adjacent files, memory surfaces, skill metadata, plugins, MCP server config shape, and local drift after an update. It never restarts the gateway, runs cron jobs or plugins, calls MCP tools, sends messages or probes the network, and its reports exclude raw .env, auth, cookie, session, memory and log contents.

Commands include discover, quick, full, post-update, repair-plan and fix. A repair plan turns findings into approval-required actions without writing anything. The fix command needs --plan, --approve with an action id and an explicit --hermes-home, and --execute is limited to registered executors. Today the only one is config.missing, which writes a backup manifest and then creates a minimal config.yaml stub. Reports come as JSON or Markdown, and a Russian-language overview is linked from the README.

Key features

Read-only, offline checks across profiles, gateway, cron, logs, auth, memory, skills, plugins and MCP
Post-update drift signals reported without a network fetch
Repair plans generated from JSON reports
Gated fix command with --plan, --approve and --execute
JSON and Markdown report output that omits raw secrets and payloads

When to use it

Taking a health snapshot before editing config or restarting a live Hermes agent
Verifying a Hermes setup after an upgrade
Auditing several Hermes profiles, cron jobs and MCP servers

Who it is for: Operators running several Hermes profiles, cron jobs, skills, plugins or MCP servers who want proof before touching a live runtime.

How it fits with Hermes Agent

Built for Hermes Agent. It reads the Hermes home and profiles, and the README states it is not an official Hermes replacement.

How to install Hermes Agent System Doctor

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

git clone https://github.com/AlekseiUL/hermes-system-doctor
cd hermes-system-doctor
python -m pip install -e ".[dev]"

Note: Early preview: only one repair executor exists, and the uvx install path is planned for after package publication.

FAQ

What is Hermes Agent System Doctor?

Hermes Agent System Doctor is a Python CLI that diagnoses a local Hermes Agent installation and plans repairs. It separates facts, risks, unknowns and approval-required fixes.

How do I install Hermes Agent System Doctor?

Clone the repository, change into it and run python -m pip install -e ".[dev]". The README says a uvx hermes-system-doctor path is intended only after package publication.

Does Hermes Agent System Doctor change my Hermes configuration?

Not by default. Diagnostic commands are read-only and offline. Only fix with --execute, an approved plan action and a registered executor can write, and today that means creating a missing config.yaml stub after a backup manifest.