How to Use Hermes Agent

TL;DR: Hermes Agent is an open-source AI assistant that remembers what it learns and gets smarter over time. Install with one command, configure your LLM provider, and start chatting via CLI, Telegram, Discord, or your IDE. This guide covers installation, setup, daily usage, advanced features, and how to get the most out of Hermes.

What Is Hermes Agent?

Hermes Agent is a personal AI assistant built by NousResearch that runs 24/7, remembers everything it learns, and gets more capable over time. Unlike ChatGPT or Claude that start fresh every conversation, Hermes builds a persistent model of your work, projects, and preferences.

Key capabilities:

• Remembers — Stores conversations, decisions, and code you've written
• Learns — Creates reusable skills from repeated tasks
• Multi-platform — Chat via CLI, Telegram, Discord, Slack, WhatsApp, or IDE
• Self-hosted — Runs on your laptop, $5 VPS, or cloud infrastructure
• Model agnostic — Use 200+ models via OpenRouter or direct providers
• Extensible — Plugin system for custom tools and commands

Who should use Hermes:

• Developers who want an AI pair programmer that knows their codebase
• Teams needing a shared AI assistant with multi-user support
• Power users who want 24/7 agent automation via cron scheduling
• Researchers training custom AI models with trajectory data

Installation: Step-by-Step

Prerequisites

• Operating System: macOS, Linux, or Windows (WSL recommended)
• Python: 3.10 or higher
• Git: For cloning repositories
• API Key: OpenRouter, Anthropic, OpenAI, or other LLM provider

Quick Install (Recommended)

The fastest way to install Hermes:

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

This script:

1. Clones the Hermes repository
2. Installs uv (fast Python package manager)
3. Creates a virtual environment
4. Installs all dependencies
5. Adds Hermes to your PATH

After installation, reload your shell:

source ~/.bashrc  # For bash
source ~/.zshrc   # For zsh

Verify installation:

hermes --version

You should see something like Hermes Agent v0.5.0.

Manual Install (For Developers)

If you want more control over the installation:

# Clone the repository
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create and activate virtual environment
uv venv venv --python 3.11
source venv/bin/activate  # Linux/macOS
# or
.\venv\Scripts\activate  # Windows

# Install Hermes with all features
uv pip install -e ".[all,dev]"

# Run tests to verify installation
python -m pytest tests/ -q

Install with RL Training Support

If you plan to train custom models:

# Initialize the Atropos submodule
git submodule update --init tinker-atropos

# Install with training dependencies
uv pip install -e "./tinker-atropos"

Initial Setup and Configuration

Run the Setup Wizard

First-time users should run the interactive setup:

hermes setup

The wizard will guide you through:

1. Choosing your LLM provider — OpenRouter, Anthropic, OpenAI, etc.
2. Setting API keys — Stored securely in ~/.hermes/.env
3. Configuring memory — Enable/disable persistent memory
4. Terminal backend — Local, Docker, SSH, or cloud options
5. Gateway setup — Telegram, Discord, Slack integration (optional)

Manual Configuration

If you prefer manual setup, edit the config file:

hermes config edit

Or use CLI commands:

# Set default model
hermes config set model anthropic/claude-opus-4

# Set terminal backend
hermes config set terminal.backend local

# Set API keys (auto-saves to ~/.hermes/.env)
hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set ANTHROPIC_API_KEY sk-ant-...

Configuration File Location

Hermes stores configuration in ~/.hermes/:

~/.hermes/
├── config.yaml      # Main configuration
├── .env             # API keys (do not share!)
├── memory/          # Persistent memory storage
├── skills/          # Installed skills
└── plugins/         # Custom plugins

Verify Your Setup

Run the health check:

hermes doctor

This checks:

• Configuration validity
• API key connectivity
• Memory system status
• Gateway status (if enabled)
• Terminal backend connection

Choosing Your LLM Provider

Hermes supports 200+ models through multiple providers. Here's how to choose:

OpenRouter (Recommended for Beginners)

Why: Single API key gives access to 200+ models. Free tier available.

Setup:

hermes config set model openrouter
hermes config set OPENROUTER_API_KEY sk-or-...

Popular models on OpenRouter:

Anthropic Direct

Why: Best-in-class coding and reasoning. Direct access to latest Claude models.

Setup:

hermes config set model anthropic
hermes config set ANTHROPIC_API_KEY sk-ant-...
hermes config set model.default claude-opus-4

OpenAI Direct

Why: GPT-4o and o1 models for specific use cases.

Setup:

hermes config set model openai
hermes config set OPENAI_API_KEY sk-...

Local Models (Ollama)

Why: Free, private, offline-capable.

Setup:

# Install Ollama first: https://ollama.ai
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b

Model Configuration Examples

Smart routing (expensive model for complex tasks, cheap for simple):

model:
  provider: openrouter
  default: anthropic/claude-opus-4
  fallback:
    - anthropic/claude-haiku-4-5
    - openai/gpt-4o-mini

Cost control (set spending limits):

model:
  budget:
    daily_limit: 5.00  # USD
    monthly_limit: 100.00

Basic Usage: CLI Mode

Starting Hermes

The simplest way to use Hermes:

hermes

You'll see a welcome banner and can start chatting immediately.

Basic Commands

Inside Hermes, you can:

Chat naturally:

> Hey, can you help me write a Python function to parse JSON?

Use slash commands:

> /help          # Show all commands
> /skills        # Browse available skills
> /memory        # View memory status
> /config        # View/edit configuration
> /clear         # Clear current conversation
> /history       # View past conversations

Give file-based tasks:

> Look at the file ./src/main.py and refactor the database connection

Run terminal commands:

> Run: npm install && npm run build

Hermes will ask for confirmation before executing any command.

Persistent Shell

Unlike other AI tools, Hermes maintains shell state across commands:

> cd /my/project && source venv/bin/activate
> python src/main.py  # Runs in the same shell session

The virtual environment stays active for subsequent commands.

Working with Files

Read files:

> Show me the contents of config.yaml

Edit files:

> In main.py, change the database port from 5432 to 5433

Create new files:

> Create a new file called utils.py with helper functions for date formatting

Multi-Step Workflows

Hermes excels at complex, multi-step tasks:

> I need to add user authentication to my Flask app. Can you:
> 1. Set up the database models
> 2. Create login/logout endpoints
> 3. Add JWT token generation
> 4. Write tests for the auth flow

Hermes will work through each step, asking for confirmation along the way.

Messaging Gateway: Telegram, Discord, Slack

Hermes can run as a bot on multiple messaging platforms, so you can interact with it from your phone or team chat.

Telegram Setup

1. Create a bot:

• Open Telegram and search for @BotFather
• Send /newbot and follow prompts
• Copy the bot token

2. Configure Hermes:

hermes config set TELEGRAM_BOT_TOKEN 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

3. Start the gateway:

hermes gateway setup telegram
hermes gateway start

4. Start chatting:

• Find your bot on Telegram
• Send /start
• Chat as you would in the CLI

Discord Setup

1. Create a Discord application:

• Go to https://discord.com/developers/applications
• Create new application
• Go to "Bot" section and create a bot
• Copy the bot token

2. Invite bot to your server:

• Go to "OAuth2" → "URL Generator"
• Select "bot" scope
• Copy the generated URL and open it

3. Configure Hermes:

hermes config set DISCORD_BOT_TOKEN MTIzNDU2...
hermes gateway setup discord
hermes gateway start

4. Use in Discord:

• Mention the bot: @Hermes help me write a function...
• Or use in DMs

Slack Setup

1. Create a Slack app:

• Go to https://api.slack.com/apps
• Create new app from scratch
• Add "Bot" permissions

2. Install to workspace and copy token

3. Configure Hermes:

hermes config set SLACK_BOT_TOKEN xoxb-...
hermes gateway setup slack
hermes gateway start

Multi-Platform Usage

You can run multiple gateways simultaneously:

hermes gateway start --all

Hermes syncs conversation state across all platforms.

IDE Integration: VS Code, JetBrains

Hermes integrates directly with your code editor via the Agent Communication Protocol (ACP).

VS Code Integration

1. Install the ACP extension:

• Open VS Code
• Go to Extensions (Ctrl+Shift+X)
• Search for "Agent Communication Protocol"
• Install the extension

2. Configure Hermes as backend:

hermes acp start

3. Use in VS Code:

• Open the ACP sidebar
• Select Hermes as your agent
• Chat and use slash commands directly in the editor

JetBrains Integration (IntelliJ, PyCharm, etc.)

1. Install the ACP plugin:

• Open Settings → Plugins
• Search for "ACP" or "Agent Communication Protocol"
• Install and restart IDE

2. Start Hermes ACP server:

hermes acp start

3. Configure in JetBrains:

• Go to Settings → Tools → AI Agents
• Add Hermes as an ACP backend
• Test connection

Zed Editor

Zed has native ACP support:

1. Configure in Zed settings:

{
  "agent": {
    "provider": "acp",
    "endpoint": "hermes"
  }
}

2. Start Hermes:

hermes acp start

Memory and Learning System

Hermes's superpower is its memory architecture. Here's how to use it effectively.

Memory Types

Episodic Memory: Stores specific conversations and sessions. You can search and retrieve past interactions.

> /memory search "database migration"

Semantic Memory: Builds knowledge graphs about your projects, preferences, and patterns.

> /memory projects

Procedural Memory (Skills): Creates reusable skills from repeated tasks.

> /skills list

Session Search

Find relevant past work with semantic search:

> /memory search "How did we handle JWT expiration last week?"

Hermes searches your entire history and summarizes results.

Memory Nudges

Hermes proactively surfaces relevant information:

[Hermes]: I noticed you're working on the auth system. Last Tuesday you
mentioned a problem with JWT expiration. Want to revisit that?

Context Compression

Hermes automatically compresses context to avoid hitting limits:

• Gateway compression at 85% context usage
• Agent-level compression at 50% (configurable)

This allows indefinite conversations without manual context management.

Export and Backup

Export memory:

hermes memory export ~/backup/hermes-memory.json

Import memory:

hermes memory import ~/backup/hermes-memory.json

Skills and Plugins

What Are Skills?

Skills are reusable workflows that Hermes can execute. Think of them as macros for complex tasks.

Built-in skills include:

• code_review — Review code for bugs and style
• debug_session — Systematic debugging workflow
• api_tester — Test REST/GraphQL APIs
• git_workflow — Git operations with best practices
• documentation — Generate docs from code

Browse and Install Skills

View available skills:

> /skills list

Install a skill:

> /skills install code_review

Use a skill:

> /skills run code_review ./src/auth.py

Custom Skills

Create custom skills in ~/.hermes/skills/:

# ~/.hermes/skills/my_skill.py
from hermes.skills import Skill

class MyCustomSkill(Skill):
    name = "my_custom_skill"
    description = "Does something useful"

    def execute(self, context):
        # Your skill logic here
        return "Skill executed successfully"

Plugin System

Plugins extend Hermes with custom tools, commands, and hooks.

Create a plugin:

# ~/.hermes/plugins/my_tool.py
from hermes.tools import Tool

class MyCustomTool(Tool):
    name = "my_tool"
    description = "A custom tool for specific tasks"

    def run(self, **kwargs):
        # Tool logic here
        return {"result": "success"}

Plugin types:

• Tools — New capabilities the agent can use
• Commands — New slash commands
• Hooks — Lifecycle event handlers (before/after turns)

Advanced Features

Cron Scheduling

Schedule automated tasks:

# Ask Hermes to create a scheduled task
> Set up a daily digest of my GitHub notifications at 9am

Or configure manually in config.yaml:

cron:
  - name: "Daily digest"
    schedule: "0 9 * * *"
    command: "/skills run github_digest"
    model: "anthropic/claude-haiku-4-5"

Subagent Delegation

Hermes can spawn subagents for parallel work:

> I need you to review all the PRs in my repo and summarize the changes

Hermes will spawn multiple subagents to work in parallel, then synthesize results.

Voice Mode

Push-to-talk in CLI:

hermes --voice

Voice notes in Telegram/Discord:

• Send a voice message
• Hermes transcribes and responds

Discord voice channels:

• Hermes can join voice channels
• Speak and listen in real-time

Browser Control

Hermes integrates with Browser Use CLI 2.0 for web automation:

> Go to github.com and find the top 5 trending Python repos

Or connect to live Chrome via CDP:

hermes browser connect --cdp

MCP Integration

Hermes supports Model Context Protocol (MCP) servers:

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    git:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-git"]

Worktree Mode

Run Hermes in an isolated git worktree:

hermes -w

Multiple agents can work on the same repo concurrently without conflicts.

Run Other Agents Inside Hermes

Hermes can run other AI agents as subagents:

> Use claude-code to review this pull request

This is useful for leveraging specialized agents for specific tasks.

Troubleshooting

Common Issues

"API key not found"

# Verify API key is set
hermes config get OPENROUTER_API_KEY

# Re-set if needed
hermes config set OPENROUTER_API_KEY sk-or-...

"Model not available"

# List available models
hermes models list

# Change model
hermes config set model anthropic/claude-opus-4

"Gateway failed to start"

# Check gateway status
hermes gateway status

# Restart gateway
hermes gateway stop
hermes gateway start

"Memory corruption detected"

# Backup current memory
hermes memory export ~/backup/memory-backup.json

# Reset memory
hermes memory reset

# Re-import if needed
hermes memory import ~/backup/memory-backup.json

Getting Help

Built-in help:

> /help

View logs:

hermes logs tail --follow

Run diagnostics:

hermes doctor

FAQ

How much does Hermes cost to run?

Hermes itself is free. You only pay for LLM usage. Typical costs:

• Light use (few tasks/day): $5-15/month with OpenRouter
• Moderate use (regular development): $20-50/month
• Heavy use (24/7 automation): $50-200/month

Using local models (Ollama) is free but requires hardware.

Can Hermes run 24/7?

Yes. Deploy Hermes on a VPS:

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

# Run as systemd service
hermes service install
hermes service start

Is Hermes suitable for enterprise use?

Yes. Enterprise features include:

• Multi-user gateway mode with session isolation
• PII redaction for compliance
• Supply chain security hardening
• Self-hosted deployment
• Audit logging

How do I migrate from OpenClaw?

hermes claw migrate --dry-run  # Preview
hermes claw migrate            # Full migration
hermes doctor                  # Verify

Can I use Hermes without internet?

Yes, with local models:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull qwen2.5-coder:32b

# Configure Hermes
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b

What's the difference between Hermes and ChatGPT?

How do I backup my Hermes data?

# Export everything
hermes export --all ~/backup/hermes-full-backup.tar.gz

Can Hermes access my local files?

Hermes can only access files you explicitly reference or directories you've granted permission to. By default, it has no access to your filesystem.