Harnesses

Hermes Agent

Nous Research's agent. Everything under ~/.hermes, sessions in one SQLite database. And one-shots that outlive their deadline.
IDhermes16 / 1725 paths · env + project
Harness

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
Inferred 0 / 25

Access

GetgetHarness("hermes")
CLIharnesses 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}.

Callinvoke(prompt, options)2 of 6 modes
  • 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.

PathsgetHarness("hermes")25 templates · 5 groups

config

  • ~/.hermes/config.yamluserofficiallinux, darwin

    Model, toolsets, MCP servers under mcp_servers, shell hooks. HERMES_HOME moves the whole home.

  • %LOCALAPPDATA%/hermes/config.yamluserofficialwin32

    Model, toolsets, MCP servers under mcp_servers, shell hooks. HERMES_HOME moves the whole home.

  • ~/.hermes/.envuserofficiallinux, darwin

    API keys and secrets.

  • %LOCALAPPDATA%/hermes/.envuserofficialwin32

    API keys and secrets.

  • ~/.hermes/auth.jsonuserofficiallinux, darwin

    OAuth logins such as Nous Portal, plus the credential pool.

  • %LOCALAPPDATA%/hermes/auth.jsonuserofficialwin32

    OAuth logins such as Nous Portal, plus the credential pool.

  • ~/.hermes/plugins/userofficiallinux, darwin

    One directory per plugin, each with a plugin.yaml and Python code.

  • %LOCALAPPDATA%/hermes/plugins/userofficialwin32

    One directory per plugin, each with a plugin.yaml and Python code.

sessions

  • ~/.hermes/state.dbdataofficiallinux, darwin

    Every session with its full message history and an FTS5 index.

  • %LOCALAPPDATA%/hermes/state.dbdataofficialwin32

    Every session with its full message history and an FTS5 index.

  • ~/.hermes/sessions/dataofficiallinux, darwin

    Gateway session JSON files and request dumps.

  • %LOCALAPPDATA%/hermes/sessions/dataofficialwin32

    Gateway session JSON files and request dumps.

instructions

  • .hermes.mdprojectofficialall

    Or HERMES.md, found up to the git root. One project file type loads, and this one wins.

  • AGENTS.override.mdprojectofficialall

    Loaded instead of the AGENTS.md beside it.

  • AGENTS.mdprojectofficialall

    Every one from the git root down to the cwd, the deepest last. Outside git, the cwd only.

  • CLAUDE.mdprojectofficialall

    The cwd only.

  • .cursorrulesprojectofficialall

    The cwd only.

  • ~/.hermes/SOUL.mduserofficiallinux, darwin

    The identity slot, always loaded. Hermes reads no AGENTS.md from its home.

  • %LOCALAPPDATA%/hermes/SOUL.mduserofficialwin32

    The identity slot, always loaded. Hermes reads no AGENTS.md from its home.

skills

  • .hermes/skills/projectofficialall

    Loaded once hermes skills trust has trusted the repo.

  • .agents/skills/projectofficialall

    Same trust gate.

  • ~/.hermes/skills/userofficiallinux, darwin

    skills.external_dirs in config.yaml adds more.

  • %LOCALAPPDATA%/hermes/skills/userofficialwin32

    skills.external_dirs in config.yaml adds more.

hooks

  • ~/.hermes/hooks/userofficiallinux, darwin

    Gateway hooks, a HOOK.yaml and a handler.py each. Shell hooks live in config.yaml.

  • %LOCALAPPDATA%/hermes/hooks/userofficialwin32

    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.

EnvenvOverrides2 variables
  • HERMES_HOME~/.hermesconfig · sessions · instructions · skills · hooks · linux, darwin
  • HERMES_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

CalldetectHarness()env, then project

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.