Hermes Agent
Hermes Agent
- hermes
Nous Research's agent. YAML config, SOUL.md up front and a gateway behind every one-shot.
- Invoke
- 2 of 6 · official
- Models
- no listing
- MCP
- not mapped
- Agents file
- none stable
Access
- Get
getHarness("hermes") - CLI
harnesses paths hermes --json - Tryhermes in the explorer
Hermes Agent is Nous Research's agent CLI, written in Python. The binary is hermes, and hermes --version says which one you have.
Where does it keep everything? On Linux and macOS, it's ~/.hermes/. On Windows, it's %LOCALAPPDATA%/hermes. Set HERMES_HOME to move the whole home.
Inside, config.yaml holds the model, toolsets, MCP servers and shell hooks. API keys go in .env. OAuth logins, including Nous Portal, go in auth.json. Plugins live in plugins/, each with plugin.yaml and Python code. Gateway hooks live in hooks/, each with HOOK.yaml and handler.py.
Sessions share one SQLite database, state.db, with full message history and an FTS5 search index. The sessions/ folder beside it holds gateway session JSON files and request dumps.
Which project instructions win? Hermes picks one file type per session. It checks .hermes.md or HERMES.md first, up to the git root. Next comes AGENTS.override.md, which replaces the AGENTS.md beside it.
Then comes AGENTS.md. Inside git, Hermes reads each one from the root down to the working directory. The deepest comes last. Outside git, it reads only the working directory's file. Finally, it checks CLAUDE.md, then .cursorrules.
SOUL.md in the home is the identity slot, and it always loads. An AGENTS.md in the home, though? Hermes doesn't read one. So there's no agentsFile, and agents sync skips Hermes.
Skills live in ~/.hermes/skills/. Config can add folders through skills.external_dirs. Project skills in .hermes/skills/ and .agents/skills/ need hermes skills trust first.
Skills sync owns ~/.hermes/skills/. It also writes an empty .no-bundled-skills into the Hermes home when it's missing. The report names the marker when it writes one. With --check, it names the marker without writing.
That marker matters more than it looks. Without it, hermes update copies the whole bundled catalog into the folder, and after a sync that folder is your shared agntn skills folder. With it, Hermes seeds only its own hermes-agent skill. One skill moves in, not the whole library.
MCP servers sit under mcp_servers in config.yaml. The library has no YAML editor yet, so the registry lists no MCP config for Hermes, and mcp-servers sync skips it.
How does a run work? hermes --oneshot=<prompt> prints only the final answer. The prompt stays glued to --oneshot=, so one that starts with a dash isn't read as a flag. For structured output, hermes chat --query=<prompt> --oneshot --format stream-json emits JSONL. Expect an init line, text deltas and a result with session ID and token counts.
Every library run adds --ignore-rules. That leaves AGENTS.md, SOUL.md, memory and preloaded skills out of the prompt. A live check planted a secret word in AGENTS.md, and it stayed out of the answer, SOUL.md too. The tools can still open those files from disk. It's a prompt boundary, not a wall.
--ignore-user-config stays off on purpose. It drops the model from config.yaml, and then Hermes refuses to start without both --provider and --model.
The library sends model through -m. It accepts provider:model, such as openrouter:anthropic/claude-sonnet-4. A bare id goes to the configured provider. There's no model listing to run, so listModels refuses with that hint instead. effort goes to --reasoning. Unknown values fail with invalid_params.
One-shot runs skip approval prompts. That's the full agent, with every tool. There's no read-only or advisor mode. -t none fails, and a single toolset doesn't help, because tool search still reaches the rest. The library refuses readOnly and advisor requests before spawning.
What happens at a deadline? Less than you'd hope. The hermes process the library spawns is only a client. Each one-shot goes through the profile's gateway, which Hermes starts on demand. Killing the client detaches it, and the turn keeps running.
Fitting for a messenger. It drops the message off and doesn't wait for the reply. In a live check, a turn slept for 25 seconds and then wrote a file, though its client was killed at 12. Your environment variables reach the client too, not the tools the turn runs.
Hermes exports HERMES_AGENT=true and AI_AGENT=hermes-agent to commands it runs. detectHarness reads HERMES_AGENT, and it checks Hermes near the end, so Claude running inside Hermes is still Claude. Project markers are .hermes, .hermes.md and HERMES.md. Audio and video aren't verified, so both are false.
Capabilities and invocation
- mcp: yes
- vision: yes
- audio: no
- video: no
- tools: yes
- streaming: yes
Binary hermes, evidence official. --ignore-rules keeps AGENTS.md, SOUL.md, memory and preloaded skills out of the prompt; the tools can still read them. --ignore-user-config is left off, since it drops the configured model and a run then needs --provider and --model both. One-shot runs skip approval prompts. Every run goes through the profile's gateway, which Hermes starts on demand: a deadline or a cancel only detaches and the turn finishes anyway, and the caller's env reaches the client, not the tools. No advisor or read-only mode: -t takes no empty toolset, and tool search still reaches the rest. Checked on 0.23.3. Model selection appends -m {model}.
- advisor{}rejected
- advisor · json{ structured: true }rejected
- read-only{ readOnly: true }rejected
- read-only · json{ readOnly: true, structured: true }rejected
- agent{ tools: true }
--oneshot={prompt} --ignore-rules - agent · json{ tools: true, structured: true }
chat --query={prompt} --oneshot --format stream-json --ignore-rules
Paths
Templates as the registry stores them. ~, ${HOME}, ${TMPDIR} and %VAR% expand in resolve(); entries tagged with a platform are dropped on the others. Open in the explorer to see them expanded for a home directory of your choice.
config
~/.hermes/config.yamlModel, toolsets, MCP servers under mcp_servers, shell hooks. HERMES_HOME moves the whole home.
%LOCALAPPDATA%/hermes/config.yamlModel, toolsets, MCP servers under mcp_servers, shell hooks. HERMES_HOME moves the whole home.
~/.hermes/.envAPI keys and secrets.
%LOCALAPPDATA%/hermes/.envAPI keys and secrets.
~/.hermes/auth.jsonOAuth logins such as Nous Portal, plus the credential pool.
%LOCALAPPDATA%/hermes/auth.jsonOAuth logins such as Nous Portal, plus the credential pool.
~/.hermes/plugins/One directory per plugin, each with a plugin.yaml and Python code.
%LOCALAPPDATA%/hermes/plugins/One directory per plugin, each with a plugin.yaml and Python code.
sessions
~/.hermes/state.dbEvery session with its full message history and an FTS5 index.
%LOCALAPPDATA%/hermes/state.dbEvery session with its full message history and an FTS5 index.
~/.hermes/sessions/Gateway session JSON files and request dumps.
%LOCALAPPDATA%/hermes/sessions/Gateway session JSON files and request dumps.
instructions
.hermes.mdOr HERMES.md, found up to the git root. One project file type loads, and this one wins.
AGENTS.override.mdLoaded instead of the AGENTS.md beside it.
AGENTS.mdEvery one from the git root down to the cwd, the deepest last. Outside git, the cwd only.
CLAUDE.mdThe cwd only.
.cursorrulesThe cwd only.
~/.hermes/SOUL.mdThe identity slot, always loaded. Hermes reads no AGENTS.md from its home.
%LOCALAPPDATA%/hermes/SOUL.mdThe identity slot, always loaded. Hermes reads no AGENTS.md from its home.
skills
.hermes/skills/Loaded once hermes skills trust has trusted the repo.
.agents/skills/Same trust gate.
~/.hermes/skills/skills.external_dirs in config.yaml adds more.
%LOCALAPPDATA%/hermes/skills/skills.external_dirs in config.yaml adds more.
hooks
~/.hermes/hooks/Gateway hooks, a HOOK.yaml and a handler.py each. Shell hooks live in config.yaml.
%LOCALAPPDATA%/hermes/hooks/Gateway hooks, a HOOK.yaml and a handler.py each. Shell hooks live in config.yaml.
Empty
commandspromptTemplatestempThat is not the same as the feature being missing.
Env overrides
Variables the harness reads to move a root. The path is the default while the variable is unset; resolve() applies a set one to temp.
HERMES_HOME~/.hermesconfig · sessions · instructions · skills · hooks · linux, darwinHERMES_HOME%LOCALAPPDATA%/hermesconfig · sessions · instructions · skills · hooks · win32
MCP servers
No MCP config file is mapped, so listMcpServers returns nothing for it and syncMcpServers skips it.
Detection
envVars
- HERMES_AGENT
projectMarkers
- .hermes
- .hermes.md
- HERMES.md
Persistence
- SQLite - state.db holds sessions and messages. (official)
- YAML - config.yaml. (official)
- JSON - Gateway sessions, auth.json. (official)
- Markdown - SOUL.md and memories/MEMORY.md, USER.md. (official)
No stable user-scope instructions file, so syncAgentsFiles skips this harness.