Hermes Agent Academy

The Big Idea

Hermes Agent is an open-source AI agent framework by Nous Research. It's not a chatbot you talk to once and forget — it's a long-running agent that lives in your terminal, remembers you across sessions, creates its own reusable skills from experience, and reaches you through Telegram, Discord, Slack, and a dozen other platforms.

Why It's Different

• Self-improving skills — When Hermes solves a complex task, it writes a skill file so next time it doesn't re-reason from scratch.
• Persistent memory — It remembers who you are, your preferences, and what you've worked on.
• Multi-platform gateway — Same agent on CLI, Telegram from your phone, Discord from your server, or email.
• Provider-agnostic — Swap between Claude, GPT, Gemini, DeepSeek, or local models without changing anything else.
• 40+ built-in tools — Terminal, file ops, web search, browser automation, image gen, code execution, and more.

What People Actually Use It For

• 🧑‍💻 Software development — Code review, PR management, debugging, project scaffolding
• 📊 Research & analysis — Web research, data extraction, report generation
• 🤖 Always-on assistant — Telegram/Discord bot for your team or personal use
• ⏰ Task automation — Daily briefings, system monitoring, cron-scheduled workflows
• 🏠 Home automation — Smart home control via Home Assistant integration

✓ Mark Complete

One-Line Install

Open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer handles everything — Python 3.11, Node.js, ripgrep, ffmpeg, the repo clone, virtual environment, and your initial provider setup.

Post-Install

Reload your shell so the hermes command is on PATH:

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

Verify it worked:

hermes --version

Platform Notes

• Windows — Install WSL2 first (wsl --install in PowerShell), then run the curl command inside WSL2.
• macOS — Works natively. No special steps.
• Linux — Works natively.
• Android (Termux) — Same curl one-liner; the installer auto-detects Termux.

After Install — Take a Tour

Before configuring a provider, poke around:

hermes doctor        # Check health of your installation
hermes config path   # Where is config.yaml?
hermes --help        # See all commands

✓ Mark Complete

Pick Your Model Provider

This is the most important setup step. Run the interactive picker:

hermes model

Best Choices for Beginners

Provider	Why Start Here
Nous Portal	Zero-config subscription, OAuth login, one click
OpenRouter	One API key gives you access to 200+ models
OpenAI Codex	OAuth via ChatGPT account — free tier available
Anthropic	Best coding performance with Claude models

Minimum Requirements

Your model must have at least a 64K token context window. Most cloud models (Claude, GPT, Gemini, Qwen, DeepSeek) qualify. Local models need --ctx-size 65536 (llama.cpp) or -c 65536 (Ollama).

Your First Conversation

Launch Hermes:

hermes            # Classic CLI
hermes --tui      # Modern TUI (recommended)

You'll see a welcome banner with your model, available tools, and skills. Start with something easy to verify:

❯ What's my current disk usage? Show the top 5 largest directories.

Verify It Works

Success indicators:

• Banner shows your chosen model/provider ✓
• Replies without error ✓
• Can use tools (terminal, file read, web search) ✓
• Conversation continues for multiple turns ✓

Then test session resume:

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

✓ Mark Complete

Five Slash Commands You'll Actually Use

Command	What It Does
/help	Show all available commands
/tools	List tools available in this session
/model	Switch models interactively
/new or /reset	Start a fresh session
/retry	Resend the last message (useful after a failed tool call)

Multi-Line Input

You're not limited to one-liners. Send multi-line prompts with:

• Alt+Enter or Ctrl+J — Works in every terminal
• Shift+Enter — Works in Kitty, foot, WezTerm, Ghostty

Interruption

Type a new message + Enter, or Ctrl+C, to interrupt long-running tasks without losing progress.

Other Important CLI Commands

hermes doctor          # Diagnose issues
hermes config edit     # Open config.yaml in $EDITOR
hermes config set KEY VAL   # Set a config value
hermes tools list      # See all tools and their status
hermes update          # Update to latest version
hermes chat -q "..."   # Single query (non-interactive)

✓ Mark Complete

What Are Tools?

Tools are Hermes' superpowers — the things it can do besides talk. File operations, web search, browser automation, terminal commands, image generation, code execution, memory management, and more.

Key Toolsets

Toolset	What It Provides
web	Web search & content extraction
browser	Browser automation (local Chromium or cloud)
terminal	Shell commands & process management
file	Read, write, search, patch files
code_execution	Sandboxed Python execution
vision	Image analysis
image_gen	AI image generation
skills	Skill browsing & management
memory	Persistent cross-session memory
delegation	Subagent task delegation
cronjob	Scheduled task management

Managing Tools

hermes tools              # Interactive enable/disable (curses UI)
hermes tools list         # Show all tools and their status
hermes tools enable web   # Enable web search toolset
hermes tools disable vision  # Disable vision toolset

✓ Mark Complete

What Are Skills?

Skills are reusable procedural knowledge — markdown files with YAML frontmatter that tell Hermes how to handle a specific type of task. When Hermes solves a complex problem, it can automatically generate a skill so next time it doesn't reason from scratch.

The Self-Improvement Loop

After a task completes (typically 5+ tool calls), Hermes runs a self-evaluation:

• What did I do?
• What worked?
• What failed?
• Is this worth capturing as a skill?

If yes, it writes a skill file. Next time a similar task arrives, it loads the relevant skill and performs ~40% faster (Nous Research benchmarks).

How to Use Skills

hermes skills list               # List installed skills
hermes skills search kubernetes   # Search the skills hub
hermes skills install openai/skills/k8s  # Install from hub
hermes skills browse              # Browse all available skills
hermes skills config              # Enable/disable per platform

In session, load a skill explicitly:

/skill k8s    # Load a skill mid-conversation

Community Skills to Install First

• Code review & quality checks
• Research & web analysis
• System administration & monitoring
• Content creation & blog writing

✓ Mark Complete

Three-Layer Memory Architecture

Hermes doesn't forget you between sessions. Memory works in three layers:

• Session memory — What happened in the current conversation (context window)
• Long-term memory — Facts about you, your preferences, environment, and lessons learned (MEMORY.md + USER.md)
• Skill memory — Reusable procedures stored as skill files that load into future sessions

How Memory Works

Memory is stored as markdown files at ~/.hermes/memories/. At the start of each session, relevant memories are injected into context. The implementation is well-engineered: atomic writes, file locking, character budgets, frozen snapshots for cache stability.

Session Management

hermes sessions list         # List recent sessions
hermes sessions browse       # Interactive picker
hermes sessions rename ID T  # Rename a session
hermes --continue            # Resume most recent session
hermes -c                    # Short form

Inside a session, name it for easy recall later:

/title "Project X — Database Migration Plan"

Configuring Memory

hermes memory setup     # Configure memory provider
hermes memory status    # Check current memory provider
hermes config set memory.memory_enabled true
hermes config set memory.user_profile_enabled true

✓ Mark Complete

The Gateway — Hermes' Killer Feature

The messaging gateway is what makes Hermes different from every other agent. It runs as a background process and connects Hermes to 14+ platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, DingTalk, Feishu, WeCom, and more.

Setup

hermes gateway setup     # Interactive platform configuration
hermes gateway run       # Start gateway (foreground)
hermes gateway install   # Install as background service
hermes gateway start     # Start the service
hermes gateway status    # Check status

Telegram Quick Start

1. Open Telegram, search for @BotFather
2. Send /newbot and follow the prompts to get a bot token
3. Get your numeric user ID from @userinfobot (not your @username)
4. Run hermes gateway setup and paste the token
5. Start the gateway: hermes gateway start

Discord Quick Start

1. Create a bot in Discord Developer Portal
2. Enable Message Content Intent (Bot → Privileged Gateway Intents)
3. Copy the bot token
4. Run hermes gateway setup and select Discord

Home Channel

In any platform, use /sethome to set the current chat as your home channel — the default destination for scheduled deliveries.

✓ Mark Complete

Schedule Tasks That Run While You Sleep

Cron jobs let Hermes run tasks on a schedule — daily summaries, periodic checks, automated reports — without you being present. Results are delivered to your home channel.

Creating a Cron Job

hermes cron create "0 9 * * *"    # Every day at 9 AM
hermes cron create "30m"           # Every 30 minutes
hermes cron create "every 2h"      # Every 2 hours

Full command syntax:

hermes cron create SCHEDULE --prompt "Your task prompt here" --name "Daily Briefing"

Managing Jobs

hermes cron list            # List all jobs
hermes cron pause ID        # Pause a job
hermes cron resume ID       # Resume a job
hermes cron edit ID         # Edit schedule, prompt, delivery
hermes cron run ID          # Trigger on next tick
hermes cron remove ID       # Delete a job
hermes cron status          # Scheduler status

Example: Daily Research Briefing

A cron job that searches Hacker News for AI papers and sends you a summary on Telegram:

hermes cron create "0 8 * * *" \
  --prompt "Search Hacker News for the top AI/ML papers today. Summarize the 3 most interesting ones in 3 bullets each. Deliver to Telegram." \
  --name "AI Daily Briefing"

✓ Mark Complete

Voice Mode

Hermes supports real-time voice interaction — speak to it and hear responses. Available in CLI, Telegram, Discord, and Discord VC.

Setup

# Install voice extras
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

# In-session: toggle voice
/voice on       # Voice-to-voice (speak and listen)
/voice tts      # Text-to-speech only (type, hear response)
/voice off      # Disable voice

STT (Speech-to-Text) Providers

Provider	Free?	Setup
Local faster-whisper	✅ Free	pip install faster-whisper
Groq Whisper	✅ Free tier	Set GROQ_API_KEY
OpenAI Whisper	💰 Paid	Set VOICE_TOOLS_OPENAI_KEY

Personality (SOUL.md)

Define who Hermes is with a SOUL.md file. A few lines of text permanently change how it talks to you:

# ~/.hermes/SOUL.md

You are a sharp, reliable tool with good judgment.
Truth over comfort. Clarity over completeness.
Direct, warm when the moment calls for it.
Never performatively cheerful.
Assume competence. Skip the beginner scaffolding unless asked.
Prefer the boring reliable solution over the clever fragile one.

Apply it:

hermes config set agent.personality soul

✓ Mark Complete

What is MCP?

Model Context Protocol is an open standard that lets AI agents connect to external tool servers. MCP servers provide specialized capabilities — GitHub operations, database queries, file system access, web APIs — that Hermes can call on demand.

Adding MCP Servers

# Add via CLI
hermes mcp add github --command "npx -y @modelcontextprotocol/server-github"

# Add via config (~/.hermes/config.yaml)
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
  postgres:
    command: npx
    args: ["-y", "@anthropic/mcp-server-postgres"]
    env:
      DATABASE_URL: "postgresql://..."

Managing MCP

hermes mcp list              # List configured servers
hermes mcp test NAME         # Test connection
hermes mcp configure NAME    # Toggle tool selection
hermes mcp remove NAME       # Remove a server
hermes mcp serve             # Run Hermes as an MCP server

Hermes as an MCP Server

You can also run Hermes itself as an MCP server, exposing all its tools to other MCP-compatible clients:

hermes mcp serve    # Now other agents can use Hermes' tools

Add to Cursor, Windsurf, or Claude Desktop:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

✓ Mark Complete

Subagent Delegation

Hermes can spawn subagents to work on tasks in parallel — each gets its own conversation, terminal session, and toolset. Results come back to the parent agent.

When to Delegate

Use delegation for...	Better to run directly
Parallel research on 3 topics	One quick web search
Debugging a complex error	Reading a single file
Building frontend + backend simultaneously	A simple terminal command
Multi-file code generation	One-line file write

Spawning Independent Instances

For long-running, fully isolated tasks, spawn a separate Hermes process:

# One-shot mode (fire and forget)
hermes chat -q "Research GRPO papers and write summary to ~/research/grpo.md"

# Background for long tasks
hermes chat -q "Set up CI/CD pipeline for ~/myapp" &

Worktree Mode (Parallel Coding)

Use -w (worktree mode) when spawning agents that edit code — prevents git conflicts:

# Agent A: backend
hermes -w chat -q "Build REST API for user management"

# Agent B: frontend
hermes -w chat -q "Build React dashboard for user management"

✓ Mark Complete

Profiles — Multiple Personalities

Run multiple independent Hermes instances with isolated configs, sessions, skills, and memory:

hermes profile create work --clone-from default
hermes profile create personal
hermes profile list
hermes profile use work      # Set as default
hermes -p personal           # Run with a specific profile

Config Reference

Key sections you'll actually change:

Section	Key Settings
model	default, provider, base_url
agent	max_turns (default 90)
terminal	backend (local/docker/ssh/modal)
memory	memory_enabled, provider
security	redact_secrets, approvals.mode

Security Best Practices

• Command approval — Default: prompts before destructive commands. Set smart mode to auto-approve low-risk ones: hermes config set approvals.mode smart
• Secret redaction — Auto-mask API keys in logs: hermes config set security.redact_secrets true
• PII redaction — Hash user IDs in gateway messages: hermes config set privacy.redact_pii true
• Sandboxed terminal — Run commands in Docker: hermes config set terminal.backend docker
• Environment separation — Secrets in .env, config in config.yaml. Never commit .env.

✓ Mark Complete

The Core Innovation

Hermes' self-improvement loop is what makes it different from every other agent. Here's how it actually works:

1. Task completion — After a task with 5+ tool calls, a background process evaluates the trajectory
2. Self-evaluation — "What did I do? What worked? What failed? Is this worth capturing?"
3. Skill generation — If yes, it writes a markdown skill file with YAML frontmatter, capturing the approach, edge cases, and domain knowledge
4. Future loading — Next time a similar task arrives, the agent loads the relevant skill instead of reasoning from scratch
5. Refinement — Skills that miss edge cases get updated on subsequent uses. Bad skills get pruned

What the Data Shows

Nous Research benchmarks: agents with 20+ self-created skills complete similar future research tasks 40% faster than fresh instances. This is "40% less tokens and time spent to reach equivalent output" — not "40% better quality."

Real-World Timeline

• 5-10 sessions — Basic context: your stack, preferences, environment
• 30+ sessions — Meaningful skill accumulation covering common workflows
• 60+ sessions — Anticipatory behavior: applies your conventions without prompting

Skill Review Discipline

Auto-generated skills vary in quality. Community wisdom says:

• You'll collect a handful of excellent skills, a pile of mediocre ones, and at least one that confidently codifies a wrong approach
• Review your skills periodically: ls ~/.hermes/skills/
• Read them, edit them, delete the bad ones, promote the good ones
• Commit excellent skills to git — they represent genuine workflow knowledge

✓ Mark Complete

From Laptop to Always-On Agent

Hermes really shines when it runs 24/7 — on a cheap VPS, a Raspberry Pi, or a serverless Modal worker. While your laptop sleeps, Hermes is running cron jobs, monitoring things, and waiting for your Telegram messages.

Option 1: Cheap VPS ($5-10/month)

Hetzner, Netcup, or any cloud provider:

# SSH into your VPS
ssh root@your-vps-ip

# Install Hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

# Configure
hermes model
hermes gateway setup

# Install as a system service
hermes gateway install

# Enable linger so service survives SSH logout
sudo loginctl enable-linger $USER

Option 2: Docker

docker run -d \
  --name hermes \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=sk-or-... \
  ghcr.io/nousresearch/hermes-agent:latest

Option 3: Serverless (Modal / Daytona)

Serverless backends hibernate when idle and wake on demand — near-zero cost for infrequent use:

hermes config set terminal.backend modal

Cost Profile

Component	Cost
VPS (Hetzner CX22)	~$4-5/month
API costs (DeepSeek V4)	~$0.50-5/month
Serverless (Modal)	Often free tier
Total	$5-15/month

✓ Mark Complete

Creating a Plugin (No Source Changes)

For custom tools, do not edit Hermes core. Create a user plugin instead:

mkdir -p ~/.hermes/plugins/my-plugin

Create plugin.yaml:

name: my-plugin
description: My custom tools
kind: tool
requires_env: [MY_API_KEY]

Create __init__.py:

def register(ctx):
    ctx.register_tool(
        name="my_tool",
        toolset="custom",
        schema={"name": "my_tool", "description": "...", "parameters": {...}},
        handler=lambda args, **kw: "result"
    )

Enable it:

hermes config set plugins.enabled [my-plugin]
# Then /reset

Writing Custom Skills

Skills are markdown files with YAML frontmatter. You can write them by hand:

---
name: my-code-review
description: "Review pull requests against team conventions"
---
When reviewing code, always check for:
1. Error handling — are all edge cases covered?
2. Test coverage — are new functions tested?
3. Naming conventions — does it match the codebase style?
...

Save to ~/.hermes/skills/ and load with /skill my-code-review.

Contributing to Hermes

Hermes is open source (MIT) and actively developed on GitHub. To contribute:

• Project layout: run_agent.py (core loop), tools/ (one file per tool), gateway/platforms/ (platform adapters)
• Adding a core tool: register in tools/registry.py, add to toolsets.py
• Testing: python -m pytest tests/ -q (~3000 tests)
• Commit conventions: fix:, feat:, refactor:, docs:, chore:
• Key rule: Never break prompt caching — don't change context, tools, or system prompt mid-conversation

✓ Mark Complete