Hermes Agent Complete Documentation Guide: Setup, CLI, Features, and Integrations

What This Guide Covers and Who It Is For

This guide is a comprehensive walkthrough of Hermes Agent, the open-source AI agent from Nous Research that lives in your terminal. It covers everything from installation and provider setup to the full CLI interface, slash commands, session management, background tasks, the Tool Gateway, and integrations with messaging platforms, MCP servers, and external memory backends. It is written for developers, system administrators, and power users who want a single source of truth for getting Hermes working and keeping it that way.

What You Need

Before you begin, you need a machine running Linux, macOS, Windows (native or WSL2), or Android via Termux. The only manual prerequisite is Git. On Linux, also make sure curl and xz-utils are installed (sudo apt install curl xz-utils on Debian/Ubuntu). For the desktop app, additionally install build-essential (sudo apt install build-essential). The installer handles everything else: Python 3.11 (via uv), Node.js v22, ripgrep, and ffmpeg. You do not need to install these manually. A model with at least 64,000 tokens of context is required; most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you are running a local model, set its context size to at least 64K (e.g. --ctx-size 65536 for llama.cpp or -c 65536 for Ollama).

Installation

Quick Install (Recommended)

The fastest path is the Hermes Desktop installer for macOS or Windows, downloadable from the Hermes Agent website. For a command-line-only install, run one of these:

Linux / macOS / WSL2 / Android (Termux)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (native)

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

After the installer finishes, reload your shell:

source ~/.bashrc   # or source ~/.zshrc

What the Installer Does

The installer clones the repository, sets up a Python virtual environment using uv, installs all dependencies, creates a hermes symlink in ~/.local/bin/hermes, and places data in ~/.hermes/. If run as root (via sudo curl ... | sudo bash), the code goes to /usr/local/lib/hermes-agent/ and the binary to /usr/local/bin/hermes, while per-user config still lives under each user's ~/.hermes/ or explicit HERMES_HOME.

Manual / Developer Installation

If you want to clone the repo and install from source for contributing or running from a specific branch, see the Development Setup section in the Contributing guide. Nix users have a dedicated setup path with a Nix flake and declarative NixOS module, though Nix is best-effort only.

Provider Setup

The single most important setup step is choosing an inference provider. Use hermes model to walk through the choice interactively:

hermes model

Fastest Path: Nous Portal

One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

hermes setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.

Setup Modes

On a fresh install, hermes setup offers three modes:

• Quick Setup (Nous Portal) -- free OAuth login, no API keys; sets up a model plus the Tool Gateway tools.
• Full Setup -- walk through every provider, tool, and option yourself (bring your own keys).
• Blank Slate -- everything starts off except the bare minimum: provider & model, File Operations toolset, and Terminal toolset. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers. Compression, checkpoints, smart routing, and memory capture are all disabled. After the minimal baseline, you choose to finish with everything disabled or walk through all configurations. Blank Slate writes an explicit platform_toolsets.cli list plus agent.disabled_toolsets, so nothing you did not choose ever loads, even after hermes update.

Supported Providers (Partial List)

Provider	Setup Method
Nous Portal	hermes model (OAuth, subscription-based)
OpenAI Codex	hermes model (ChatGPT OAuth)
GitHub Copilot	hermes model (OAuth device code flow)
Anthropic	hermes model (Claude Max + extra usage credits via OAuth; also supports API key)
OpenRouter	OPENROUTER_API_KEY in ~/.hermes/.env
Fireworks AI	FIREWORKS_API_KEY in ~/.hermes/.env
NovitaAI	NOVITA_API_KEY in ~/.hermes/.env
z.ai / GLM	GLM_API_KEY in ~/.hermes/.env
Kimi / Moonshot	KIMI_API_KEY in ~/.hermes/.env
DeepSeek	DEEPSEEK_API_KEY in ~/.hermes/.env
xAI (Grok)	XAI_API_KEY in ~/.hermes/.env
xAI Grok OAuth	hermes model (SuperGrok / Premium+ subscription)
Qwen Cloud (Alibaba DashScope)	DASHSCOPE_API_KEY in ~/.hermes/.env
AWS Bedrock	IAM role or aws configure
Google AI Studio	GOOGLE_API_KEY / GEMINI_API_KEY
Custom Endpoint	Set base URL + API key

For the full provider catalog with env vars and setup steps, see the AI Providers page.

How Settings Are Stored

Hermes separates secrets from normal config:

• Secrets and tokens go to ~/.hermes/.env
• Non-secret settings go to ~/.hermes/config.yaml

The easiest way to set values correctly is through the CLI:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

The right value goes to the right file automatically.

Running Your First Chat

hermes          # classic CLI
hermes --tui    # modern TUI (recommended)

You will see a welcome banner with your model, available tools, and skills. Try a prompt that is specific and easy to verify:

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

What success looks like:

• The banner shows your chosen model/provider
• Hermes replies without error
• It can use a tool if needed (terminal, file read, web search)
• The conversation continues normally for more than one turn

Verify Sessions Work

Before moving on, make sure resume works:

hermes --continue   # Resume the most recent session
hermes -c           # Short form

CLI Interface

Hermes Agent's CLI is a full terminal user interface (TUI) -- not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.

Running the CLI

# Start an interactive session (default)
hermes

# Single query mode (non-interactive)
hermes chat -q "Hello"

# With a specific model
hermes chat --model "anthropic/claude-sonnet-4"

# With a specific provider
hermes chat --provider nous

# Use Nous Portal
hermes chat --provider openrouter   # Force OpenRouter

# With specific toolsets
hermes chat --toolsets "web,terminal,skills"

# Start with one or more skills preloaded
hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -q "open a draft PR"

# Resume previous sessions
hermes --continue                    # Resume the most recent CLI session (-c)
hermes --resume session_id           # Resume a specific session by ID (-r)

# Verbose mode (debug output)
hermes chat --verbose

# Isolated git worktree (for running multiple agents in parallel)
hermes -w                            # Interactive mode in worktree
hermes -w -z "Fix issue #123"        # Single query in worktree

Interface Layout

The Hermes CLI shows a welcome banner with your model, terminal backend, working directory, available tools, and installed skills at a glance.

Status Bar

A persistent status bar sits above the input area, updating in real time:

⚕ claude-sonnet-4-20250514 │ 12.4K/200K │ [██████░░░░] 6% │ $0.06 │ 15m

Element	Description
Model name	Current model (truncated if longer than 26 chars)
Token count	Context tokens used / max context window
Context bar	Visual fill indicator with color-coded thresholds
Cost	Estimated session cost (or n/a for unknown/zero-priced models)
🗜️ N	Context compression count -- how many times the running session has been auto-compressed. Appears once the first compression fires.
▶ N	Active background tasks -- how many /background prompts are still running. Appears whenever at least one task is in flight.
Duration	Elapsed session time
⚠ YOLO	YOLO mode warning -- shown whenever HERMES_YOLO_MODE is on.

The bar adapts to terminal width: full layout at >= 76 columns, compact at 52-75, minimal (model + duration, plus YOLO badge when active) below 52.

Context color coding:

• Green (< 50%): Plenty of room
• Yellow (50-80%): Getting full
• Orange (80-95%): Approaching limit
• Red (>= 95%): Near overflow -- consider /compress

Use /usage for a detailed breakdown including per-category costs (input vs output tokens). On the openai-codex provider, /usage also shows any banked usage-limit resets on your ChatGPT account ("You have N resets banked - use /usage reset to activate"). /usage reset redeems one banked reset, fully restoring your 5-hour and weekly limits. Hermes refuses to redeem while your limits are not exhausted (a banked reset restores the full allowance, so spending it early wastes it) -- pass /usage reset --force to redeem anyway.

Session Resume Display

When resuming a previous session (hermes -c or hermes --resume <id>), a "Previous Conversation" panel appears between the banner and the input prompt, showing a compact recap of the conversation history.

Keybindings

Key	Action
Enter	Send message
Alt+Enter, Ctrl+J, or Shift+Enter	New line (multi-line input). Shift+Enter requires a terminal that distinguishes it from Enter. On Windows Terminal, Alt+Enter is captured by the terminal (fullscreen toggle); use Ctrl+Enter or Ctrl+J instead.
Alt+V	Paste an image from the clipboard when supported by the terminal
Ctrl+V	Paste text and opportunistically attach clipboard images
Ctrl+B	Start/stop voice recording when voice mode is enabled (voice.record_key, default: ctrl+b)
Ctrl+G	Open the current input buffer in $EDITOR (vim/nvim/nano/VS Code/etc.). Save and quit to send the edited text as the next prompt.
Ctrl+X Ctrl+E	Emacs-style alternate binding for the external editor (same behavior as Ctrl+G).
Ctrl+C	Interrupt agent (double-press within 2s to force exit)
Ctrl+D	Exit
Ctrl+Z	Suspend Hermes to background (Unix only). Run fg in the shell to resume.
Tab	Accept auto-suggestion (ghost text) or autocomplete slash commands

Multiline paste preview: When you paste a multi-line block, the CLI echoes a compact single-line preview ([pasted: 47 lines, 1,842 chars -- press Enter to send]) instead of dumping the whole payload into the scrollback. The full content is still what gets sent; this is just display polish.

Markdown stripping in final responses: The CLI strips the most verbose markdown fences and **bold** / *italic* wrappers from final agent replies so they render as readable terminal prose rather than raw source. Code blocks and lists are preserved. This does not affect gateway platforms or tool results -- they keep their markdown for native rendering.

Slash Commands

Type / to see the autocomplete dropdown. Hermes supports a large set of CLI slash commands, dynamic skill commands, and user-defined quick commands. Common examples:

Command	Description
/help	Show command help
/model	Show or change the current model
/tools	List currently available tools
/skills browse	Browse the skills hub and official optional skills
/background <prompt>	Run a prompt in a separate background session
/skin	Show or switch the active CLI skin
/voice on	Enable CLI voice mode (press Ctrl+B to record)
/voice tts	Toggle spoken playback for Hermes replies
/reasoning high	Increase reasoning effort
/title My Session	Name the current session
/status	Show session info -- model/profile/tokens/duration -- followed by a local Session recap block. Pure local compute; no LLM call.
/sessions	Open an interactive session picker right inside the classic CLI.

Commands are case-insensitive -- /HELP works the same as /help. Installed skills also become slash commands automatically.

Quick Commands

You can define custom commands that run shell commands instantly without invoking the LLM. These work in both the CLI and messaging platforms (Telegram, Discord, etc.).

# ~/.hermes/config.yaml
quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  restart:
    type: alias
    target: /gateway restart

Then type /status, /gpu, or /restart in any chat.

Preloading Skills at Launch

If you already know which skills you want active for the session, pass them at launch time:

hermes -s hermes-agent-dev,github-auth
hermes chat -s github-pr-workflow -s github-auth

Hermes loads each named skill into the session prompt before the first turn. The same flag works in interactive mode and single-query mode.

Skill Slash Commands

Every installed skill in ~/.hermes/skills/ is automatically registered as a slash command. The skill name becomes the command:

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor

Just the skill name loads it and lets the agent ask what you need:

/excalidraw

Personalities

Set a predefined personality to change the agent's tone:

/personality pirate
/personality kawaii
/personality concise

Built-in personalities include: helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype. You can also define custom personalities in ~/.hermes/config.yaml:

personalities:
  helpful: "You are a helpful, friendly AI assistant."
  kawaii: "You are a kawaii assistant! Use cute expressions..."
  pirate: "Arrr! Ye be talkin' to Captain Hermes..."
  # Add your own!

Multi-line Input

There are two ways to enter multi-line messages:

• Alt+Enter, Ctrl+J, or Shift+Enter -- inserts a new line
• Backslash continuation -- end a line with \ to continue:

❯ Write a function that:\
1. Takes a list of numbers\
2. Returns the sum

Pasting multi-line text is supported -- use any of the newline keys above, or simply paste content directly.

Shift+Enter compatibility: Most terminals send the same byte sequence for Enter and Shift+Enter by default, so applications cannot distinguish them. Hermes recognises Shift+Enter only when the terminal sends a distinct sequence via the Kitty keyboard protocol or xterm's modifyOtherKeys mode.

Terminal	Status
Kitty, foot, WezTerm, Ghostty	Distinct Shift+Enter enabled by default
iTerm2 (recent), Alacritty, VS Code terminal, Warp	Supported once the Kitty protocol is enabled in settings
Windows Terminal Preview 1.25+	Supported once the Kitty protocol is enabled in settings
macOS Terminal.app, stock Windows Terminal (stable)	Not supported -- Shift+Enter is indistinguishable from Enter

Where the terminal cannot distinguish them, Alt+Enter and Ctrl+J continue to work everywhere. On Windows Terminal specifically, Alt+Enter is captured by the terminal (toggles fullscreen) and never reaches Hermes -- use Ctrl+Enter (delivered as Ctrl+J) or Ctrl+J directly for a newline.

Redirecting the Agent Mid-Turn

While the agent is working, you can send a correction without starting a new turn:

• Type a new message + Enter -- redirects the active turn using your correction
• Ctrl+C -- interrupt the current operation (press twice within 2s to force exit)
• Completed tool work and reasoning already shown stay in context
• A running tool reaches its safe boundary before the correction is applied

Busy Input Mode: The display.busy_input_mode config key controls what happens when you press Enter while the agent is working:

Mode	Behavior
"interrupt" (default)	Your message redirects the active turn. Model generation restarts with displayed reasoning and completed work preserved; running tools finish first
"queue"	Your message is silently queued and sent as the next turn after the agent finishes
"steer"	Your message is injected into the current run via /steer, arriving at the agent after the next tool call -- no interrupt, no new turn

# ~/.hermes/config.yaml
display:
  busy_input_mode: "steer"   # or "queue" or "interrupt" (default)

"queue" mode prepares a separate follow-up turn. "steer" always waits for the next tool-result boundary. The default "interrupt" mode responds sooner during model generation while avoiding cancellation of a running tool. Use /stop when you want to cancel the turn and its foreground work. Unknown values fall back to "interrupt". "steer" has two automatic fallbacks: if the agent has not started yet, or if images are attached, the message falls back to "queue" behavior so nothing is lost.

You can also change it inside the CLI:

/busy queue
/busy steer
/busy interrupt
/busy status

First-touch hint: The first time you press Enter while Hermes is working, Hermes prints a one-line reminder explaining the /busy knob. It only fires once per install; onboarding.seen.busy_input_prompt in config.yaml records that it was shown. Delete that key to see the tip again.

Suspending to Background

On Unix systems, press Ctrl+Z to suspend Hermes to the background -- just like any terminal process. The shell prints a confirmation:

Hermes Agent has been suspended. Run `fg` to bring Hermes Agent back.

Type fg in your shell to resume the session exactly where you left off. This is not supported on Windows.

Tool Progress Display

The CLI shows animated feedback as the agent works:

Thinking animation (during API calls):

◜ (｡•́︿•̀｡) pondering... (1.2s)
◠ (⊙_⊙) contemplating... (2.4s)
✧٩(ˊᗜˋ*)و✧ got it! (3.1s)

Tool execution feed:

┊ 💻 terminal `ls -la` (0.3s)
┊ 🔍 web_search (1.2s)
┊ 📄 web_extract (2.1s)

Cycle through display modes with /verbose: off -> new -> all -> verbose. This command can also be enabled for messaging platforms.

Tool Preview Length: The display.tool_preview_length config key controls the maximum number of characters shown in tool call preview lines (e.g. file paths, terminal commands). The default is 0, which means no limit -- full paths and commands are shown.

# ~/.hermes/config.yaml
display:
  tool_preview_length: 80   # Truncate tool previews to 80 chars (0 = no limit)

This is useful on narrow terminals or when tool arguments contain very long file paths.

Session Management

Resuming Sessions

When you exit a CLI session, a resume command is printed:

Resume this session with: hermes --resume 20260225_143052_a1b2c3
Session: 20260225_143052_a1b2c3
Duration: 12m 34s
Messages: 28 (5 user, 18 tool calls)

Resume options:

hermes --continue                          # Resume the most recent CLI session
hermes -c                                  # Short form
hermes -c "my project"                     # Resume a named session (latest in lineage)
hermes --resume 20260225_143052_a1b2c3     # Resume a specific session by ID
hermes --resume "refactoring auth"         # Resume by title
hermes -r 20260225_143052_a1b2c3           # Short form

Resuming restores the full conversation history from SQLite. The agent sees all previous messages, tool calls, and responses -- just as if you never left. Use /title My Session Name inside a chat to name the current session, or hermes sessions rename <id> <name> from the command line. Use hermes sessions list to browse past sessions.

Session Storage

CLI sessions are stored in Hermes's SQLite state database under ~/.hermes/state.db. The database keeps:

• session metadata (ID, title, timestamps, token counters)
• message history
• lineage across compressed/resumed sessions
• full-text search indexes used by session_search

Some messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store.

Context Compression

Long conversations are automatically summarized when approaching context limits:

# In ~/.hermes/config.yaml
compression:
  enabled: true
  threshold: 0.50   # Compress at 50% of context limit by default

# Summarization model configured under auxiliary:
auxiliary:
  compression:
    model: ""   # Leave empty to use the main chat model (default). Or pin a cheap fast model, e.g. "google/gemini-3-flash-preview".

When compression triggers, middle turns are summarized while the first 3 and last 20 turns are always preserved.

Background Sessions

Run a prompt in a separate background session while continuing to use the CLI for other work:

/background Analyze the logs in /var/log and summarize any errors from today

Hermes immediately confirms the task and gives you back the prompt:

🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..."
Task ID: bg_143022_a1b2c3

How It Works

Each /background prompt spawns a completely separate agent session in a daemon thread:

• Isolated conversation -- the background agent has no knowledge of your current session's history. It receives only the prompt you provide.
• Same configuration -- the background agent inherits your model, provider, toolsets, reasoning settings, and fallback model from the current session.
• Non-blocking -- your foreground session stays fully interactive. You can chat, run commands, or even start more background tasks.
• Multiple tasks -- you can run several background tasks simultaneously. Each gets a numbered ID.

Results

When a background task finishes, the result appears as a panel in your terminal:

╭─ ⚕ Hermes (background #1) ──────────────────────────────────╮
│ Found 3 errors in syslog from today:                         │
│ 1. OOM killer invoked at 03:22 -- killed process nginx       │
│ 2. Disk I/O error on /dev/sda1 at 07:15                      │
│ 3. Failed SSH login attempts from 192.168.1.50 at 14:30      │
╰──────────────────────────────────────────────────────────────╯

If the task fails, you will see an error notification instead. If display.bell_on_complete is enabled in your config, the terminal bell rings when the task finishes.

Use Cases

• Long-running research -- "/background research the latest developments in quantum error correction" while you work on code
• File processing -- "/background analyze all Python files in this repo and list any security issues" while you continue a conversation
• Parallel investigations -- start multiple background tasks to explore different angles simultaneously

Background sessions do not appear in your main conversation history. They are standalone sessions with their own task ID (e.g., bg_143022_a1b2c3).