Type hermes doctor into your terminal and Hermes runs a full health check across your entire install — config, credentials, plugins, skills, logging, connectivity, database health, cron jobs and disk usage — then prints exactly what it found and, where a fix exists, the explicit command to repair it. The hermes doctor command is the single most useful troubleshooting tool Nous Research has shipped for the agent, and after the September 2026 patch cycle it is also the officially recommended first move whenever sessions vanish, search returns nothing or the state database throws lock errors. Add the --fix flag and it repairs what it can safely fix on its own.
📺 Watch: NEW Hermes Agent Update is WILD!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside · Want AI SEO help 1-on-1? Book a free SEO strategy session →
What The Hermes Doctor Command Actually Checks
According to the official Hermes Agent documentation from Nous Research, the doctor command is a one-command diagnostic sweep across the whole installation. Rather than making you hunt through logs, it inspects each subsystem in turn and reports a pass, a warning or a failure with a suggested next step. The documented checklist covers:
- Config and credentials — it validates your configuration files, verifies API keys and confirms the models you have configured are actually available.
- Dependencies and PATH — it checks that required binaries are installed and reachable.
- Plugins and skills — it confirms your installed Hermes agent plugins and skills load cleanly.
- Database health — it inspects the state.db session store for corruption, stale locks and damaged search indexes.
- Cron jobs, logging, connectivity and disk usage — the operational plumbing that quietly breaks scheduled automations when it fails.
That last group matters more than most people expect. If you run scheduled jobs through your agent — content pipelines, monitoring, the kind of systems the Agent OS is built around — a silent cron or disk failure costs you days of missed runs. The doctor command surfaces those problems in seconds.
Hermes Doctor --Fix: What It Repairs On Its Own
Running the command with the --fix flag moves it from diagnosis to treatment. The official docs state it auto-fixes what it can, and the headline capability is search-index repair: when state.db has full-text-search corruption — the classic symptom is session search returning nothing while the sessions themselves still exist — hermes doctor --fix rebuilds the FTS index. The docs list hermes sessions repair as the equivalent explicit route for the same rebuild.
There is one hard rule, stated in bold terms in the state database recovery guide: do not run hermes doctor --fix while the gateway is still up. A repair running while a gateway process still holds the database was one of the documented triggers for the very corruption you are trying to fix. Stop the gateway first, run the repair, verify, then bring everything back up.
If you want a Hermes agent that runs your business instead of breaking at 2am — with the full Agent OS, prompt libraries and weekly live coaching — check out the AI Profit Boardroom → get the complete agent stack here. Prefer to map your setup 1-on-1 first? Book a free SEO strategy session and plan it with Julian directly.
Why September 2026 Made The Doctor Essential
The doctor command exists in its current form because of a rough patch in Hermes Agent's session store, and the fix timeline is worth knowing because it changes how safe the command is to run. The v0.21.0 Pantheon release of 31 August 2026 consolidated thousands of commits and shipped the big features, but it also introduced session-store reliability problems that Nous Research spent September correcting.
Per the official release notes, the v0.21.2 patch of 11 September 2026 fixed session-store lock contention, false database-corruption reports, full-text-search failure isolation, malformed-row crashes and cross-profile database access. Two changes matter directly for the doctor: the release notes state that doctor --fix previously "would checkpoint under a live holder" — exactly the unsafe-repair scenario described above — and that it now "refuses a checkpoint it can't prove is safe". In other words, the current doctor will decline to run a repair that could make things worse, which older builds would happily attempt. The same patch made malformed session rows non-fatal, so even a partially damaged database stays recoverable.
Three days later the 14 September 2026 update addressed expiring dashboard sessions and state.db writer leaks — the full list is in the Hermes Agent 0.21.3 patch notes breakdown. The practical takeaway: update to the latest release before you run repairs, because the doctor itself got safer with each of these patches.
The Symptoms That Mean You Should Run It
The state database recovery guide describes the corruption symptoms that justify reaching for the doctor first, and they are all easy to recognise:
- Sessions that vanish from your history.
- The sessions list erroring out instead of loading.
- Session search returning nothing when you know the conversations exist.
- Repeated lock errors that survive a restart.
If you are seeing lock errors specifically, the dedicated Hermes state.db locked fix guide walks through that exact failure in more depth. And note what is not on this list: your agent's markdown memory. The Hermes memory system lives in plain files, not in state.db, so a corrupted session store does not touch what your agent knows about you — it touches your conversation history and search.
The Right Repair Order For A Damaged State Database
The recovery documentation lays out an escalation ladder, and following it in order is the difference between a two-minute fix and a lost session history. Based on the official guide, the sequence looks like this:
- Stop everything first. Run hermes gateway stop and make sure every process that can open the profile database is down. The docs are explicit: keep them stopped for the complete repair and verification window.
- Run hermes doctor. It diagnoses the store and, per the docs, reports the explicit repair command for whatever it finds — so you are never guessing which tool applies.
- Run hermes doctor --fix for the automatic repair path, typically the FTS rebuild.
- Check before you write. For a manual pass, hermes sessions repair --check-only inspects without changing anything, then hermes sessions repair performs the actual repair.
- Escalate to recovery for structural damage. If the database is structurally corrupt rather than just index-damaged, hermes sessions recover with the --inspect-only flag shows what is salvageable, and running it again with an --output path writes the recovered sessions to a fresh database file, leaving the damaged original untouched.
The guide also includes verification steps after repair — checking the FTS stale marker, confirming triggers exist and comparing canonical row counts — so you can prove the fix worked rather than hoping.
Mistakes That Make Corruption Worse
Two warnings from the official documentation deserve their own section because both look harmless and both can destroy a recoverable database. First, the one already covered: never run the repair while the gateway holds the database. Second, never copy state.db, state.db-wal and state.db-shm as separate files with a normal copy command. The docs put it plainly: those three files are one live SQLite image, and copying them independently gives you a backup that is internally inconsistent — corrupt the moment you try to restore it. If you want a safe backup, stop the gateway first, then copy all three together.
It is the same lesson that applies across your whole agent setup, from your Hermes workspace to your scheduled jobs: the agent's power comes from persistent local state, and persistent local state rewards a little operational discipline.
Is The Hermes Doctor Command Safe To Run?
The plain hermes doctor command is read-only diagnosis — it inspects and reports, so it is safe to run any time, on any build. The --fix variant writes to your database, which is why the September 2026 hardening matters: on a current build, the release notes say it refuses any checkpoint it cannot prove is safe, and with the gateway stopped the documented repair path is the one Nous Research itself recommends. The residual risk sits in running old builds or repairing a live database — both avoidable in under a minute.
One thing the doctor does not do is tell you which model brain to run behind your agent. Diagnostics keep the machine healthy; picking the engine is a separate decision, and the Goldie Bench write-up covers how the current crop of models compares on real agent workloads. For day-to-day visibility between doctor runs, the Hermes dashboard command is the complementary tool: the dashboard shows you live status while the doctor diagnoses and repairs — two different commands for two different jobs.
The verdict is simple: learn this one command before you need it. When your agent misbehaves, hermes doctor is the fastest route from "something is wrong" to a named problem with a documented fix — and since the 11 September 2026 patch it is finally cautious enough to trust with the repair itself.
If you want working systems instead of debugging sessions — done-for-you agent workflows, the full Agent OS zip and five live coaching calls a week — check out the AI Profit Boardroom → join the operators inside. Want a personal roadmap instead? Book a free SEO strategy session and get your AI plan built 1-on-1.
