Hermes Agent

Hermes Agent is a full terminal UI — multiline editing, slash-command autocomplete, session history, interrupt-and-redirect, and streaming tool output. Built for people who never leave the shell.

Everything you reach for daily

The handful of commands and keys that cover most of a session — full detail in the sections below.

Run it

• hermes — Start an interactive session (or --tui).
• hermes -z "…" — One-shot: prompt in, final answer out.
• hermes -c [name] — Resume most recent (matching) session.
• hermes -r <id> — Resume an exact session by ID/title.
• hermes chat -q "…" — Single non-interactive query, then exit.
• hermes setup — First-run wizard (providers & keys).

In-session

• /help — List every slash command.
• /model — Show / switch model (provider:model).
• /new — Fresh session (/reset is the same).
• /compress — Summarize context now, manually.
• /retry — · Resend last turn · drop last exchange.
• /quit — Exit (/exit, /q).

Keys

• Send — Enter
• Interrupt — Ctrl C
• New line — Meta Enter/Esc Enter
• Autocomplete — Tab
• Clear screen — Ctrl L
• History — ↑↓

From zero to first prompt

Set up once with the wizard, then start chatting. One command for the easiest path.

1. Install

Grab the agent from the repo, then the wizard handles providers and keys.

# install via the official repo
# (NousResearch/hermes-agent)

2. First-run setup

One command runs the wizard: provider, API key, terminal backend. --portal does a one-shot Nous Portal OAuth.

hermes setup
hermes setup --portal   # one-shot Nous Portal OAuth

3. Start chatting

Default is an interactive session. A -q query runs once, then exits.

hermes
hermes chat -q "Summarize the latest PRs"

4. Exit & resume

Leave with Ctrl+D or /quit, come back later with --continue.

hermes --continue   # -c

KEY: Two surfaces: hermes (the interactive session) and hermes --tui (modal TUI with mouse). Same engine, different surface. --cli forces the classic line-based REPL if your config defaults to TUI.

!: hermes model vs /model. Run hermes model from your terminal (outside a session) to add providers and API keys. /model inside a session only switches between what’s already set up.

Three boxes. One home directory.

Everything lives under ~/.hermes/. Sessions are stored in SQLite, and config is one YAML file.

~/.hermes/ (home dir) → config.yaml (one config) → .env (credentials) → state.db (sessions) → Session (resumable turn history)

Profile

An isolated Hermes instance with its own config, sessions, skills, and home. Use named profiles for hard separation between work and personal setups.

hermes profile create work --clone
hermes -p work chat

Session

One conversation, stored in SQLite and fully resumable. The agent sees every prior message and tool call when you resume.

hermes --resume latest
hermes sessions list

Config

A single ~/.hermes/config.yaml controls display, compression, personalities, quick commands, and more. Many keys can be changed mid-session.

hermes config
hermes doctor

Interactive, single-shot, or scripted

Same agent, three wrappers. Pick the one that matches the job.

The default REPL

Interactive

hermes

Multiline editing, autocomplete, history, redirect mid-turn. hermes --tui for the modal TUI.

One run, then exit

Single query

hermes chat -q "Summarize PRs"

-q runs one non-interactive query and exits. Plain hermes to stay in the session.

Pure one-shot

Scripted

hermes -z "Capital of France?"
# → Paris.

Prompt in, final answer out — nothing else on stdout. Built for shell scripts and CI.

Useful chat options

Global options

The daily keymap

Modeled on Claude Code / Codex / OpenCode multiline conventions. New line is Meta+Enter (Esc then Enter also works). On Windows Terminal use Ctrl+J or Ctrl+Enter for a newline (Alt+Enter is captured by the terminal).

Composing

• Send message — Enter
• New line — Meta Enter/Esc Enter/Ctrl J
• Edit in $EDITOR — Ctrl G/Ctrl X Ctrl E
• Stash draft (stack) — Ctrl S
• Accept suggestion — Tab
• Input history — ↑↓
• Paste image — Alt V

Controlling

• Interrupt agent — Ctrl C
• Force exit (2×) — Ctrl C×2
• Exit session — Ctrl D
• Clear screen — Ctrl L
• Suspend (Unix) — Ctrl Z
• Voice record — Ctrl B
• Paste text — Ctrl V

Shell mode

• Run shell command — !git status
• Zero cost no LLM call
• Not in history context stays clean
• Approvals apply dangerous cmds still gated

!: Shell mode: start a line with ! to run it yourself without spending a model turn — !git status, !pytest -x. The command and its output never enter the conversation.

Type / and pick

Commands are case-insensitive (/HELP = /help). Installed skills also become slash commands automatically.

• /help — Show all available commands.
• /model [provider:model] — Show or switch model; provider: tab-completes.
• /new — · Start a fresh session (new ID + empty history).
• /clear — Clear the screen and start a new session (CLI only).
• /retry — Resend your last message.
• /undo — Drop the last user/assistant exchange from context.
• /title <name> — Name the current session.
• /resume [name] — Resume a previously-named session.
• /compress — Summarize context manually, now.
• /rollback [n] — List / restore filesystem checkpoints (needs --checkpoints).
• /background — · Run a prompt in a parallel background session.
• /stop — Kill running background processes.
• /provider — Show available providers + the active one.
• /personality <name> — Change tone (concise, pirate, kawaii…).
• /reasoning [level|show|hide] — none/low/minimal/medium/high/xhigh; show/hide the block.
• /skin [name] — Show or switch the active CLI skin.
• /voice [on|off|tts|status] — Voice input / spoken replies.
• /verbose — Cycle tool-preview verbosity.
• /tools [list|disable|enable] — Manage enabled tools.
• /toolsets — List available toolsets.
• /skills [search|browse|inspect|install|list] — Search, install, and manage skills.
• /reload-mcp — Reload MCP server connections from config.
• /usage — Token / cost stats for the current session.
• /status — Session info — gateway only; the CLI shows it in the banner.
• /quit — · · Exit the CLI.

Leave, come back, pick up where you stopped

Resuming restores the full conversation from SQLite — messages, tool calls, and responses.

Resume

hermes --continue                # -c, most recent
hermes -c "my project"           # latest matching title
hermes --resume <session_id>     # -r, exact ID
hermes --resume latest           # same as -c
hermes --resume "refactoring auth"
hermes --resume latest --in ./dir

Manage

hermes sessions list
hermes sessions browse
hermes sessions rename <id> <title>
hermes sessions delete <id>
hermes sessions export out.jsonl
hermes sessions prune --older-than 90d
hermes sessions stats

↺: Compression. Long conversations auto-summarize near the context limit, keeping the first 3 and last 4 turns intact. A fast auxiliary model (default google/gemini-3-flash-preview) writes the summary. The 🗜️ badge in the status bar shows how many times compression fired.

Any model, /model away

Set up providers from the terminal wizard, then switch freely mid-session.

Add providers

Run from outside a session to add providers, run OAuth flows, and enter API keys.

hermes model

Switch mid-session

Only switches between already-configured models. provider:model tab-completes.

/model anthropic/claude-opus-4.6
/model openrouter:anthropic/claude-opus-4.6

Fallbacks

Configure fallback providers tried when the primary errors.

hermes fallback

Change behavior without changing the model

Everything lives in ~/.hermes/config.yaml. Credentials stay in ~/.hermes/.env.

Quick commands

Custom slash commands that run shell instantly, no LLM.

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

Compression & auxiliary

compression:
  enabled: true
  threshold: 0.50   # compress at 50% context

auxiliary:
  compression:
    model: "google/gemini-3-flash-preview"   # default fast summarizer

Display

display:
  interface: cli          # or tui
  busy_input_mode: "interrupt"  # | queue | steer
  tool_preview_length: 80       # 0 = no limit
  cli_multiline_shortcuts: true

Personalities

personalities:
  helpful: "You are a helpful assistant."
  pirate: "Arrr! Talk like a captain."

# zsh
hermes completion zsh >> ~/.zshrc
# bash
hermes completion bash >> ~/.bashrc
# fish
hermes completion fish > ~/.config/fish/completions/hermes.fish

Hermes in pipelines

For shell scripts, CI, and cron, hermes -z is the purest entry point.

1. One-shot — answer=$(hermes -z "summarize this" < file.txt) — prompt in, final answer out, nothing else.
2. Per-run overrides — hermes -z "…" --provider deepseek --model deepseek-chat, or HERMES_INFERENCE_MODEL=… hermes -z "…".
3. Usage report — --usage-file /tmp/usage.json writes tokens, cost, and session ID — even on failure.
4. Send messages — hermes send posts a one-shot to a messaging platform (Telegram, Discord, Slack…) with no agent loop.

Read back usage

hermes -z "summarize this repo" \
  --usage-file /tmp/usage.json
jq .estimated_cost_usd /tmp/usage.json

Query from a file

hermes chat --query-file - < prompt.txt

Nothing is shell-interpreted — quotes, $(…), and backticks arrive verbatim.

The hermes surface

The most useful top-level commands. Run hermes --help for the complete, authoritative list.

• hermes chat — Interactive or one-shot chat with the agent.
• hermes model — Choose default provider + model (wizard).
• hermes setup — Setup wizard (add --portal for one-shot).
• hermes auth — Manage credentials — add, list, status, logout.
• hermes status — Show agent, auth, and platform status.
• hermes doctor — Diagnose config and dependency issues.
• hermes config — Show, edit, migrate, query config.
• hermes profile — Manage isolated profiles.
• hermes skills — Browse, install, publish, audit skills.
• hermes tools — Configure enabled tools per platform.
• hermes plugins — Manage plugins (install/enable/disable).
• hermes mcp — Manage MCP servers.
• hermes memory — Configure external memory provider.
• hermes sessions — Browse, export, prune, rename sessions.
• hermes logs — View, tail, filter log files.
• hermes gateway — Run/manage the messaging gateway service.
• hermes send — One-shot message to a platform, no LLM.
• hermes cron — Inspect and tick the scheduler.
• hermes insights — Token / cost / activity analytics.
• hermes dashboard — Web dashboard (config, keys, sessions).
• hermes serve — Headless backend server.
• hermes update — Pull latest code and reinstall.
• hermes version — Print the installed version.
• hermes uninstall — Remove Hermes Agent.
• hermes completion — Print shell completion scripts.
• hermes security audit — Supply-chain audit (OSV.dev).
• hermes backup / import — Back up / restore the Hermes home dir.

Fast diagnosis

Isolate whether a problem comes from your setup or from Hermes itself.

hermes chat --safe-mode -q "repro the issue"