Hermes

Vendor: Hermes Install name: hermes Status: Preview Native config: ~/.hermes/config.yaml

InstallationCopy Anchor Link

apothem install --harness hermes

The adapter translates the shared profile to the Hermes Agent user-global configuration file and installs Apothem support cohorts under the harness root.

Files written: ~/.hermes/config.yaml, the profile document ~/.hermes/apothem/rules/00-apothem-profile.md, and support files under ~/.hermes/.apothem/support/

The profile document ends with an Apothem support files section that names the absolute directory under ~/.hermes/.apothem/support/ each repository-style citation (rules/<name>.md, templates/..., hooks/...) resolves against.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared profile and renders the native YAML config, including the profile's MCP inventory. The MCP servers come from the profile's mcp_servers section. They are rendered into config.yaml on each install and update, not copied as files. The adapter also adds ~/.hermes/.apothem/support/skills to skills.external_dirs, the list of extra skill directories Hermes reads, which is how Hermes finds the installed skills. The entry goes after any entries you already list, and your other keys stay as they are. The profile's identity, preferences, and rules go into the profile document. Shared commands, skills, helper definitions, rules, templates, and hook prompts land as support material under ~/.hermes/.apothem/support/.

Compatibility notesCopy Anchor Link

Preview adapter. Hermes loads the Apothem skills through skills.external_dirs, but it does not load the rest of the support tree or the profile document on its own: nothing else in config.yaml and none of the context files Hermes reads point there, so after install Hermes runs without Apothem's rules or hooks.

Name clashes. Hermes documents this order of precedence for skills: the project's skills (<project>/.hermes/skills/ and <project>/.agents/skills/), then ~/.hermes/skills/, then skills.create_dir, then the folders listed under skills.external_dirs. The Apothem directory is an external_dirs entry, so it comes last. The Hermes docs reviewed do not state which copy Hermes loads when two locations hold a skill of the same name; Apothem reads the order as earlier locations winning, so expect a skill of the same name that you keep in an earlier location to take precedence over the Apothem copy. Apothem writes only to config.yaml and under ~/.hermes/.apothem/support/, never into those earlier locations, so install, update, and uninstall do not replace a skill you keep there.

apothem update keeps keys you add to config.yaml, including skills.config and your own skills.external_dirs entries. The adapter writes the profile's MCP inventory under the top-level mcp_servers key, where Hermes reads MCP servers. Earlier Apothem releases wrote it under auxiliary.mcp, which Hermes reads as the auxiliary model for MCP tool dispatch; both apothem update and apothem uninstall remove that block when it still matches what such a release would write from your current shared profile (see Uninstalling for when it stays). (Hermes behavior per its user guide pages on skills, read 2026-10-24, and MCP, read 2026-10-02.)

Comments in config.yaml. Apothem rewrites the file with a YAML library that drops comments. When the file carries comments of yours and the entry is missing, Apothem leaves the file untouched and install stops with a message that names the key. Add the entry yourself, then run the install again:

skills:
  external_dirs:
    - ~/.hermes/.apothem/support/skills

An entry you add yourself counts as yours: if you already list this directory, Apothem keeps your entry as it is and uninstall leaves it in place.

VerificationCopy Anchor Link

apothem verify --harness hermes

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile.
3. skills.external_dirs in the native config lists ~/.hermes/.apothem/support/skills. Without that entry Hermes does not load the installed skills; apothem update adds it back.
4. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness hermes

Re-derives the native config from the current shared profile state; the Apothem entry in skills.external_dirs stays listed once however often you update. Run after editing ~/.config/apothem/profile.yaml or upgrading the installed Apothem package.

UninstallingCopy Anchor Link

apothem uninstall --harness hermes

Removes what the adapter added: the mcp_servers entries and the skills.external_dirs entry its install recorded in config.yaml (your own keys stay, including your own external_dirs entries and skills.config, and the file is deleted only when Apothem created it and nothing of yours is left), the profile document, and the support tree. The shared profile YAML and Apothem engine are unaffected.

An install made by an earlier release, which wrote the profile's servers under auxiliary.mcp, also has that block removed when it still matches what that release would write from your current shared profile at ~/.config/apothem/profile.yaml. This is the same rule apothem update applies, so uninstalling without updating first leaves no stale block while the profile's MCP servers are unchanged. A block you have edited, one that no longer matches your current profile's MCP servers, or one with no readable shared profile to compare against, stays in place, and the rest of your auxiliary settings always stay.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI