Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.
What makes Hermes different:
Self-improving through skills — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
Persistent memory across sessions — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
Multi-platform gateway — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
Many surfaces — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
Provider-agnostic — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
Profiles — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
Extensible & themeable — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
This skill is a hub. The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — load the matching reference (below) before answering; do not answer detail questions from the body alone.
This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
Good verification targets:
CLI commands: hermes --help, hermes <command> --help, and hermes_cli/main.py
# Install (shell installer — sets up uv, Python, the venv, and the launcher)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
hermes
# Single query
hermes chat -q "What is the capital of France?"# Setup wizard / pick model+provider / health check
hermes setup
hermes model
hermes doctor
# Other surfaces
hermes desktop # launch the native desktop app (alias: hermes gui)
hermes dashboard # web admin panel + embedded chat
hermes proxy # OpenAI-compatible local proxy backed by your OAuth provider
Key Paths
~/.hermes/config.yaml Main configuration (settings — never secrets)
~/.hermes/.env API keys and secrets ONLY (under $HERMES_HOME if set)
$HERMES_HOME/skills/ Installed skills
~/.hermes/skins/ Custom themes (see references/themes.md)
~/.hermes/desktop-plugins/ Desktop app UI plugins (see references/desktop-plugins.md)
~/.hermes/tui-widgets/ TUI widget apps (see references/tui-widgets.md)
~/.hermes/pets/ Installed pet mascots (see references/petdex.md)
~/.hermes/state.db Canonical session store (SQLite + FTS5)
~/.hermes/sessions/ Gateway routing index, request dumps, *.jsonl transcripts
~/.hermes/logs/ Gateway and error logs
~/.hermes/auth.json OAuth tokens and credential pools
~/.hermes/hermes-agent/ Source code (if git-installed)
Profiles use ~/.hermes/profiles/<name>/ with the same layout. When a profile is active, resolve the real home from $HERMES_HOME — never hardcode ~/.hermes.
Routing Table — load the reference for the task
User wants...
Load
CLI commands, subcommands, flags, "how do I run X"
"Can app X use my Nous Portal subscription/OAuth?"
references/portal-auth-for-third-party-apps.md
Two theming rules that hold even without loading the reference: you apply skins yourself (hermes config set display.skin <name> — every surface repaints live within ~a second; don't tell the user to run /skin), and to tweak one color, edit the ACTIVE skin (hermes skin set <key> <hex>) — never fork default, which drops the palette and resets the background.
Spawning Additional Hermes Instances
Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.
When to Use This vs delegate_task
delegate_task
Spawning hermes process
Isolation
Separate conversation, shared process
Fully independent process
Duration
Minutes (bounded by parent loop)
Hours/days
Tool access
Subset of parent's tools
Full tool access
Interactive
No
Yes (PTY mode)
Use case
Quick parallel subtasks
Long autonomous missions
One-Shot Mode
terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)
# Background for long tasks:
terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
Interactive PTY Mode (via tmux)
Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
Prefer delegate_task for quick subtasks — less overhead than spawning a full process
Use -w (worktree mode) when spawning agents that edit code — prevents git conflicts
Set timeouts for one-shot mode — complex tasks can take 5-10 minutes
Use hermes chat -q for fire-and-forget — no PTY needed
Use tmux for interactive sessions — raw PTY mode has \r vs \n issues with prompt_toolkit
For scheduled tasks, use the cronjob tool instead of spawning — handles delivery and retry
"delegate_task is capped at N" reports — see references/delegate-task-concurrency-diagnosis.md. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
"Can $external_app use my Nous Portal subscription / OAuth?" — see references/portal-auth-for-third-party-apps.md. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
Surfaces (quick orientation)
Desktop app (hermes desktop / hermes gui) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — references/desktop-plugins.md.
Web dashboard (hermes dashboard) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded hermes --tui chat. Secured behind an OAuth/token gate.
Ink TUI (hermes --tui or display.interface: tui) — terminal UI with docked widget apps — references/tui-widgets.md.
OpenAI-compatible proxy (hermes proxy) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
Hard Invariants (never violate, regardless of what you loaded)
Never break prompt caching — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
Message role alternation — never two assistant or two user messages in a row; only tool results can repeat.
Secrets in .env, settings in config.yaml — never tell a user to put a non-credential setting in .env.
Profile-safe paths — get_hermes_home() in code, $HERMES_HOME when resolving paths in a session.
Never hand-edit config.yaml for the user — use hermes config set KEY VAL; a stray indent can corrupt the file and break the live gateway.
