NousResearch/hermes-agent instruction manual

1. Purpose, scope, and relationship to Claude Code

Hermes Agent is an MIT-licensed, Python-based autonomous agent from Nous Research. It provides its own terminal UI, messaging gateway, browser dashboard, native desktop app, tools, model-provider routing, memory, skills, scheduling, subagents, and plugin middleware. The supplied first-party files describe it as a self-improving agent: it can retain agent-curated memory, search earlier sessions with FTS5 and LLM summaries, create and refine skills from experience, and model a user across sessions. It also supports the agentskills.io format.

**Claude Code classification: standalone application / companion, installed separately and run alongside Claude Code.** The repository metadata mentions Claude and Claude Code only as topics. None of the supplied files documents a Claude Code plugin, hook, MCP server specifically for Claude, skill installed into Claude Code, or interception of Claude Code. Hermes is therefore best understood as an alternative general-purpose agent that can coexist with Claude Code, not an extension of it. Its model support may include Anthropic, but using an Anthropic model is not the same as extending Claude Code.

Hermes can run locally, on a VPS or GPU system, or through documented terminal backends: local, Docker, SSH, Singularity, Modal, Daytona, and—according to the current English README—Vercel Sandbox. Some translated READMEs list only six backends, so the English main README is the clearest current evidence. Research features include batch trajectory generation and trajectory compression. No independent validation of performance, security, costs, or the “only agent” claim is supplied.

2. Installation, setup, models, tools, updates, and diagnosis

For Linux, macOS, WSL2, and the documented Termux path, use the first-party installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc    # or: source ~/.zshrc
hermes

Native Windows uses PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The Windows installer handles uv, Python 3.11, Node.js, ripgrep, ffmpeg, and—when ordinary Git is absent—an isolated MinGit installation under `%LOCALAPPDATA%\hermes\git`. Native Windows uses `%LOCALAPPDATA%\hermes`; Linux-style installations use `~/.hermes`. Termux has a separate tested guide and uses `.[termux]` because full voice dependencies are not Android-compatible.

After installation, these documented commands expose the main administrative functions:

hermes              # open interactive chat
hermes setup        # configure everything with the setup wizard
hermes model        # choose provider and model
hermes tools        # configure enabled tools
hermes config set   # set one configuration value
hermes config get   # print one configuration value
hermes update       # update Hermes
hermes doctor       # diagnose problems

Hermes supports Nous Portal, OpenRouter, OpenAI, custom endpoints, and other provider integrations referenced by the docs. To use Nous Portal’s OAuth login, model access, and per-backend Tool Gateway:

hermes setup --portal
hermes portal info

The Tool Gateway is documented as routing web search, image generation, text-to-speech, and cloud-browser access. Users can still supply their own key for an individual backend. Provider pricing, credential requirements, privacy, and availability remain external concerns.

3. Conversations, TUI controls, sessions, and slash commands

Run `hermes` for the normal interactive interface or `hermes --tui` for the documented React/Ink TUI entry. The TUI streams responses, reasoning and tool status; renders ANSI directly or a Markdown subset; keeps input history under `~/.hermes/.hermes_history` or `HERMES_HOME`; and communicates with a Python gateway over newline-delimited JSON-RPC. It attempts gateway crash recovery up to three times within 60 seconds.

Core conversation controls are `/new` or `/reset`, `/model [provider:model]`, `/personality [name]`, `/retry`, `/undo`, `/compress`, `/usage`, `/insights [--days N]`, and `/skills` or `/<skill-name>`. `Ctrl+C` interrupts active work, clears a draft, or exits when nothing is pending; `Ctrl+D` exits. Enter submits, Shift/Alt+Enter inserts a newline, and backslash followed by Enter is the multiline fallback. `Cmd/Ctrl+G` or `Alt+G` edits the draft in `$EDITOR`. `Ctrl+L` starts a new session. Tab accepts completion; Up/Down cycles completions, queued drafts, then history.

`!cmd` runs a shell command through the gateway; `{!cmd}` interpolates shell output before sending. These are powerful execution features and should be used only with commands the user has reviewed. Plain text entered while the agent is busy queues automatically; slash commands and shell commands execute immediately. The queue drains after responses unless an item is being edited.

The TUI directly recognizes general commands including `/help`, `/quit`, `/update`, `/clear`, `/copy`, `/paste`, `/details`, `/queue`, `/logs`, `/history`, `/save`, `/steer`, `/status`, `/title`, and `/terminal-setup`; session commands including `/sessions`, `/bg`, `/image`, `/voice`, `/branch`, `/reasoning`, and `/busy`; and operations including `/stop`, `/reload-mcp`, `/browser`, `/rollback`, `/agents`, `/replay`, `/plugins`, and `/tools`. It also provides `/billing`, `/credits`, `/setup`, `/heapdump`, and `/mem`. Unrecognized commands fall through to Python-owned plugin, skill, alias, and registry dispatch.

4. Messaging, memory, skills, automations, subagents, and safety prompts

Hermes can expose one agent through Telegram, Discord, Slack, WhatsApp, Signal, Email, and other integrations referenced by the documentation. Configure and start that surface with:

hermes gateway setup
hermes gateway start

Then message the configured bot. Shared messaging commands include `/new`, `/reset`, `/model [provider:model]`, `/personality [name]`, `/retry`, `/undo`, `/compress`, `/usage`, `/insights [days]`, and `/<skill-name>`. Use `/stop` or send a new message to interrupt; `/status` reports platform status, while `/sethome` is platform-specific. In the CLI, `/platforms` provides platform status.

Documented agent functions include persistent memory, user profiles, cross-session search, project context files that shape conversations, skill browsing and execution, autonomous skill creation after complex work, and skill improvement during use. The built-in cron scheduler runs natural-language tasks unattended and can deliver results to messaging platforms—for example, the README names daily reports, nightly backups, and weekly audits as use cases. Hermes can spawn isolated subagents for parallel workstreams and can run Python pipelines that call tools through RPC.

The TUI presents structured prompts when action needs confirmation: approvals can be allowed once, for the session, always, or denied; clarification can use choices or free text; sudo and secret requests use masked input. Approval shortcuts are `o`, `s`, `a`, and `d`; Escape or Ctrl+C denies. Tool-request middleware, described later, runs before approvals, so policy evaluates rewritten arguments rather than originals. The documentation points to command approval, direct-message pairing, and container isolation, but the supplied files do not provide a full threat model or prove sandbox coverage.

5. Desktop application and browser dashboard

Hermes Desktop is the same agent, sessions, configuration, keys, memory, and skills in an Electron/React app for macOS, Windows, and Linux. It adds streaming chat, live tool activity, side-by-side previews, a working-directory file browser, voice, settings, onboarding, and background update checks. With an existing CLI installation:

hermes desktop

The desktop app can use a managed local runtime, an explicit remote gateway, or Hermes Cloud. In remote mode, tools, terminal commands, and file operations execute on the remote gateway host—not on the display computer. First launch can connect to an existing gateway or install Hermes locally. Connection tests cover HTTP and WebSocket access, and saved connection secrets use Desktop’s encrypted configuration. Profile or connection switching preserves the shell but clears gateway-bound UI state; it does not cancel active turns or stop a backend.

For access proxies, extra per-connection headers can be configured in Settings. Desktop rejects transport- or Hermes-managed names such as `Authorization`, `Cookie`, `Host`, `Origin`, `Referer`, and `X-Hermes-Session-Token`. Projects group folders, repositories, worktrees, and sessions; detached new chats remain outside a project unless a default directory is configured.

The browser dashboard manages configuration, API keys, agent status, and active or recent sessions. Its built bundle is served by `hermes dashboard` on port 9119. For dashboard development, the documented workflow is:

cd ../
python -m hermes_cli.main web --no-open
# in another terminal
cd web/
npm install
npm run dev

Open the printed Vite URL, usually `http://localhost:5173`. The Vite server proxies `/api` to `http://127.0.0.1:9119`. `npm run build` writes the static SPA to `hermes_cli/web_dist/`; restart the dashboard to see a rebuilt bundle.

6. Provider profiles, plugins, MCP, and behavior-changing middleware

Inference providers are defined once as `ProviderProfile` plugins. Bundled profiles live under `plugins/model-providers/<name>/`; user overrides live under `$HERMES_HOME/plugins/model-providers/<name>/`. Lazy discovery occurs when code first asks for one profile or lists providers. Profiles then drive authentication registration, model catalogs, health checks, setup variables, API-mode fallback, hostname mapping, auxiliary-model selection, and transport request construction.

Documented profile hooks are: `get_hostname()` for URL detection; `prepare_messages(msgs)` for provider-specific message normalization; `build_extra_body(**ctx)` for provider body options; `build_api_kwargs_extras(**ctx)` for body and top-level arguments; `supported_reasoning_efforts(model)` for cache-only reasoning vocabularies; and `fetch_models(*, api_key)` for live catalogs. The default catalog fetch uses Bearer authentication against a models endpoint; special providers can override it.

Hermes can connect MCP servers to extend its tool set. Plugins can also register four middleware kinds: `llm_request` rewrites effective provider arguments, `tool_request` rewrites effective tool arguments, `llm_execution` wraps or replaces the provider call, and `tool_execution` wraps or replaces a tool call. Enable a bundled plugin with:

hermes plugins enable <plugin-name>

For isolated testing with one home:

export HERMES_HOME=/tmp/hermes-middleware-test
mkdir -p "$HERMES_HOME"
hermes plugins enable <plugin-name>
hermes chat --query 'Reply exactly ok'

Request middleware must return complete replacement payloads. Execution middleware normally calls `next_call(...)` exactly once and returns the expected provider response or tool result. Multiple wrappers nest in registration order. Middleware failures are fail-open; downstream execution failures remain failures. Observer hooks are for read-only telemetry, while middleware is specifically for changing or wrapping behavior.

7. OpenClaw migration and troubleshooting

During `hermes setup`, Hermes detects `~/.openclaw` and can offer migration. It can import SOUL.md, MEMORY.md and USER.md entries, user skills, command approval patterns, messaging configuration, allowed users, working-directory settings, allowlisted API keys, TTS assets, and—when a workspace target is supplied—AGENTS.md. Imported skills go under `~/.hermes/skills/openclaw-imports/`.

Use only the documented migration forms:

hermes claw migrate
hermes claw migrate --dry-run
hermes claw migrate --preset user-data
hermes claw migrate --overwrite
hermes claw migrate --help

The default command is interactive; `--dry-run` previews changes, `--preset user-data` avoids secrets, and `--overwrite` replaces conflicts. An `openclaw-migration` skill also provides an agent-guided flow with previews. Because migration can copy credentials and overwrite files, previewing first is the safer documented option.

Desktop boot logs are in `HERMES_HOME/logs/desktop.log`. Documented macOS/Linux recovery commands include:

rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
rm -rf "$HOME/.hermes/hermes-agent/venv"
tccutil reset Microphone com.nousresearch.hermes

The last command is macOS-only. Windows equivalents are:

Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"

These force first-launch setup or remove a broken virtual environment, so they are destructive recovery actions, not routine maintenance. If antivirus quarantines bundled `uv.exe`, the English README provides an attestation-and-hash verification procedure and recommends whitelisting only after authenticity is confirmed.

8. Development, testing, evaluation, website, and contribution records

For core contributions, the current English README recommends the managed checkout created by the installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

Its manual fallback creates the virtual environment outside the source tree to prevent agent-run relative-path operations from deleting the active runtime:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv ~/.hermes/venvs/hermes-dev --python 3.11
source ~/.hermes/venvs/hermes-dev/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

Desktop development runs `npm install` at repository root, then `npm run dev` in `apps/desktop`. Desktop verification uses `npm run fix`, `npm run typecheck`, `npm run lint`, `npm run test:ui`, and `npm run test:desktop:platforms`; release-path changes use `npm run test:desktop:all`. Installer builds use the documented `dist:mac`, `dist:win`, `dist:linux`, or `pack` npm scripts. TUI development supports `npm run dev`, `start`, `build`, `lint`, `fmt`, `fix`, `npm test`, and `npm run test:watch` under `ui-tui`.

The Docusaurus documentation site uses `yarn`, `yarn start`, and `yarn build`; documented deployment uses `USE_SSH=true yarn deploy` or `GIT_USER=<Your GitHub username> yarn deploy`. CI rejects ASCII box diagrams; use Mermaid, lists, or tables.

The read-tool evaluation runs hostile file fixtures through the real agent and records accuracy, calls, tokens, and time. Its documented discipline requires at least three repetitions and two models; errors count as zero accuracy. Contributor email mappings are added with `python3 scripts/add_contributor.py <email> <github-login>`; GitHub noreply addresses resolve automatically. Repository metadata identifies the project as public, unarchived, primarily Python, and MIT-licensed.