---
title: "Hermes Agent"
description: "Nous Research's agent. Everything under ~/.hermes, sessions in one SQLite database. And one-shots that outlive their deadline."
canonical_url: "https://harnesses.agntn.dev/harnesses/hermes"
---
# Hermes Agent

> Nous Research's agent. Everything under ~/.hermes, sessions in one SQLite database. And one-shots that outlive their deadline.

<harness-facts id="hermes">



</harness-facts>

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`.

<harness-sheet id="hermes">



</harness-sheet>


## Sitemap

See the full [sitemap](https://harnesses.agntn.dev/sitemap.md) for all pages.
