Nous Research · Hermes Agent

Hermes Agent
Cheat Sheet

A public, profile-aware quick reference for running, configuring, extending, and troubleshooting Hermes from CLI, Discord/Telegram gateway, cron, skills, MCP, and local tool workflows. Keep secrets in local .env files and check the official docs for current commands.

Profile: use your active profile

Version: check current docs before use

Docs: hermes-agent.nousresearch.com/docs

Config: ~/.hermes/config.yaml or ~/.hermes/profiles/<profile>/config.yaml

Print tip: this sheet is print-optimized. Use landscape if you want the tables wider.

Daily command palette

Start / ask

hermes                       # interactive chat
hermes --tui                 # modern TUI
hermes --cli                 # classic REPL
hermes chat -q "Hello"       # single query
hermes -z "Only final text"  # oneshot for scripts

Resume / isolate

hermes -c                    # continue latest
hermes -c "project name"     # continue named lineage
hermes -r <session_id>       # resume exact session
hermes -w                    # isolated git worktree

Health

hermes --version
hermes status --all
hermes doctor
hermes logs --since 1h
hermes dump                  # support summary

Configuration & important files

Config commands

hermes setup                 # full wizard
hermes setup model           # section wizard
hermes model                 # choose model/provider
hermes config                # view config
hermes config path           # config.yaml path
hermes config env-path       # .env path
hermes config edit           # open editor
hermes config set KEY VALUE  # set dotted key
hermes config check
hermes config migrate

Operational rule: config changes usually require a fresh CLI session or hermes gateway restart for messaging platforms.

Filesystem map

Thing	Default profile	Named profile
Config	`~/.hermes/config.yaml`	`~/.hermes/profiles/<name>/config.yaml`
Secrets	`~/.hermes/.env`	`~/.hermes/profiles/<name>/.env`
Skills	`~/.hermes/skills/`	`~/.hermes/profiles/<name>/skills/`
Sessions	`~/.hermes/sessions/`	`~/.hermes/profiles/<name>/sessions/`
Logs	`~/.hermes/logs/`	`~/.hermes/profiles/<name>/logs/`
OAuth/pools	`~/.hermes/auth.json`	`~/.hermes/profiles/<name>/auth.json`

High-impact config sections

modelagentterminaldisplaymemorycompressiondelegationapprovalsprivacysecuritydiscord / telegram / slack

Precedence

CLI flags override environment and config for that invocation.
Profile config isolates settings, credentials, sessions, skills, memory.
Secrets belong in .env, not config.yaml.
Tool/skill availability is snapshotted at session start.

Useful global flags

-p/--profile use profile · -m/--model model override · --provider provider override · -t/--toolsets toolset override · -s/--skills preload skills · --yolo bypass approvals · --safe-mode disable customizations.

Profiles: isolated Hermes instances

Profile commands

hermes profile list
hermes profile create <profile-name>
hermes profile create <new-profile> --clone <profile-name>
hermes profile use <profile-name>
hermes -p <profile-name> status --all
hermes profile alias <profile-name>
hermes profile export <profile-name>
hermes profile import backup.tar.gz

Profile hygiene

Installed skill ≠ external authorization. Check each profile’s .env, OAuth files, and status --all.
For concurrent Discord gateways, use separate Discord bot tokens per profile.
Set per-profile allowed channels/users, then restart that profile’s gateway.
Do not edit another profile’s skills/cron/memory unless intentionally doing cross-profile maintenance.

Messaging gateway & slash commands

Service management

hermes gateway setup
hermes gateway run           # foreground
hermes gateway install       # service
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes logs gateway --since 1h

Gateway chat commands

/help /commands /status /profile /platforms /sethome /restart /approve /deny /fast /new

Messaging gateway supports Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Home Assistant, webhooks/API server, and more.

Interactive CLI slash commands

/new /clear /retry /undo /title /compress /stop /rollback /model /tools /skills /cron /reload-mcp

Platform gotchas

Discord silent: enable Message Content Intent in the Discord Developer Portal.
Discord token collision: one bot token cannot run two profile gateways concurrently.
Telegram not connecting: verify a real BotFather token in that profile’s .env, allowed user IDs, and gateway logs.
Tool changes: require /reset or new session; gateway config changes require restart.

Tools, skills & memory

Toolsets

hermes tools                 # curses UI
hermes tools list
hermes tools enable terminal
hermes tools disable image_gen

Common toolsets: webbrowserterminalfilecode_executionvisionimage_genttsskillsmemorysession_searchdelegationcronjobcomputer_use

Effect: changes take effect in the next session, not mid-turn.

Skills

hermes skills list
hermes skills browse
hermes skills search hermes
hermes skills inspect <id>
hermes skills install <id-or-url>
hermes skills config
hermes skills check
hermes skills update
hermes -s hermes-agent,codex

Skills are reusable procedures. Use them for workflows; use memory for compact stable facts only.

Memory

hermes memory status
hermes memory setup
hermes memory off
hermes memory reset

Stores durable user/environment facts. Avoid saving temporary task progress.

File/tool discipline

Use read/write/patch/search tools for files.
Use terminal for builds, package managers, git, servers, system state.
Use browser automation when the page needs interaction.
Use delegation for parallel reasoning-heavy subtasks.

Prompt size

hermes prompt-size
hermes prompt-size --profile <profile-name>

Good for diagnosing huge skill/tool/context overhead.

Sessions, subagents & spawned agents

Session management

hermes sessions list
hermes sessions browse
hermes sessions rename <id> "Title"
hermes sessions export sessions.jsonl
hermes sessions prune --older-than 30d
hermes sessions stats

When to delegate

delegate_task: quick isolated subtask, minutes, no user interaction.
Spawn Hermes: independent mission, full tool access, hours/days.
Cron: durable scheduled automation.
Worktree mode: parallel code edits without git conflicts.

Spawn examples

hermes chat -q "Research X and write ~/x.md"
hermes -w chat -q "Implement feature Y"
tmux new-session -d -s agent1 'hermes -w'
tmux send-keys -t agent1 'Build API' Enter

Cron jobs & webhooks

Cron CLI

hermes cron list
hermes cron create "0 9 * * *"
hermes cron edit <id>
hermes cron run <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron remove <id>
hermes cron status

Schedules: 30m, every 2h, cron expressions, or one-shot ISO timestamps.

Cron design rules

Prompts must be self-contained; future runs have no current-chat context.
Use skills=[...] for reusable procedure context.
Use workdir for project-local jobs and AGENTS.md injection.
Use no_agent=true only when a script prints the exact user-facing output.
After creating: list jobs and verify enabled/state/next run.

Webhooks

hermes webhook subscribe build-done
hermes webhook list
hermes webhook test build-done
hermes webhook remove build-done

Delivery targets

origin returns to current chat; local saves only; discord home channel; explicit targets use platform:chat_id[:thread_id].

MCP — Model Context Protocol

MCP commands

hermes mcp list
hermes mcp add NAME --command "npx ..."
hermes mcp add NAME --url https://...
hermes mcp test NAME
hermes mcp configure NAME
hermes mcp remove NAME
hermes mcp serve

What it does

Registers external MCP server tools into Hermes.
Supports stdio and HTTP-style servers.
Per-server tool filtering reduces prompt/tool bloat.
Reload with /reload-mcp where supported.

Security posture

Only install trusted MCPs.
Review tool names/descriptions before enabling broadly.
Keep secrets in env/config, not prompts.
Test one server at a time when troubleshooting.

Models, providers & auth

Provider commands

hermes model                 # provider/model picker
hermes auth add              # pooled credential wizard
hermes auth list [provider]
hermes auth remove <p> <index>
hermes auth reset <provider>
hermes portal                # Nous Portal setup
hermes login --provider qwen-oauth

Common providers

Provider	Auth	Env/config
OpenRouter	API key	`OPENROUTER_API_KEY`
OpenAI Codex	OAuth	`hermes auth`
Nous Portal	OAuth	`hermes portal`
Anthropic	API key	`ANTHROPIC_API_KEY`
Gemini	API key	`GOOGLE_API_KEY` / `GEMINI_API_KEY`
Local Ollama	custom endpoint	`base_url=http://127.0.0.1:11434/v1`

Local Ollama pattern

ollama list
curl http://127.0.0.1:11434/v1/models
hermes config set model.provider custom
hermes config set model.default <ollama-model>
hermes config set model.base_url http://127.0.0.1:11434/v1
hermes config set model.api_key ollama

Restart gateway if the messaging bot should use the new model.

Security, approvals & privacy

Command approvals

hermes config set approvals.mode manual  # default
hermes config set approvals.mode smart   # LLM-assisted
hermes config set approvals.mode off     # same spirit as --yolo

Careful: --yolo / approvals off bypasses dangerous command prompts.

Secret redaction

hermes config set security.redact_secrets true
hermes config set security.redact_secrets false

Restart required. Redaction is snapshotted at startup.

Privacy & audits

hermes config set privacy.redact_pii true
hermes security
hermes secrets               # external secret sources

Run broad diagnostics carefully if redaction is off; status dumps may show configured key prefixes.

Troubleshooting patterns

Fast triage flow

Check exact profile: hermes profile list.
Run hermes -p <profile> status --all.
Run hermes -p <profile> doctor.
Inspect recent logs: hermes -p <profile> logs --since 1h.
Verify config path and env path.
Restart gateway or start a new CLI session after config/tool changes.

Frequent fixes

Tool missing: hermes tools list, enable it, then /reset.
Skill missing: hermes skills list, skills config, load with /skill name.
Aux model error: configure per-task keys like auxiliary.session_search.provider; do not set only auxiliary.provider.
Gateway crash: check gateway logs, reset failed service state if needed, then restart.
Config not applied: new session/restart; many values are read at startup.

Safe diagnostics without leaking secrets

hermes -p <profile-name> config path
hermes -p <profile-name> config env-path
hermes -p <profile-name> status --all
hermes -p <profile-name> logs --since 1h
# If sharing output publicly: enable security.redact_secrets first and restart.

Developer / contributor quick reference

Repo map

Path	Purpose
`run_agent.py`	Core conversation loop
`model_tools.py`	Tool discovery and dispatch
`toolsets.py`	Toolset definitions
`cli.py`	Interactive CLI
`hermes_cli/commands.py`	Slash command registry
`tools/`	One file per tool
`gateway/`	Messaging adapters
`cron/`	Scheduler
`tests/`	Pytest suite

Dev commands

python -m pytest tests/ -o 'addopts=' -q
python -m pytest tests/tools/ -q
python -m py_compile path/to/file.py
hermes dashboard --status
hermes dashboard --no-open
hermes update

Use get_hermes_home() for profile-safe paths. Tests redirect HERMES_HOME to temp dirs.

Adding a tool

Create tools/your_tool.py.
Register with tools.registry.registry.register(...).
Add/check toolset mapping where needed.
Handler returns JSON string.
Add tests and run targeted suite.

Adding a slash command

Add CommandDef in hermes_cli/commands.py.
Add handler in CLI path.
Add gateway handler if needed.
Verify help/autocomplete/gateway behavior.

Key rules

Never break prompt caching unnecessarily.
Preserve message role alternation.
Config in config.yaml, secrets in .env.
New tools need check_fn and requirement gating.