DEV Community

Cover image for How to Use Hermes Agent
Preecha
Preecha

Posted on

How to Use Hermes Agent

TL;DR: Hermes Agent is an open-source AI assistant that keeps persistent memory across sessions, learns reusable skills, and can run through CLI, Telegram, Discord, Slack, your IDE, or scheduled automation. This guide walks through installation, configuration, daily usage, integrations, memory, skills, and troubleshooting.

Try Apidog today

What Is Hermes Agent?

Hermes Agent is a personal AI assistant from NousResearch that can run continuously, remember prior work, and improve over time. Unlike tools that start each conversation from scratch, Hermes builds persistent context around your projects, preferences, conversations, and workflows.

Image

Core capabilities:

  • Persistent memory: stores conversations, decisions, and code context
  • Learning system: turns repeated tasks into reusable skills
  • Multi-platform access: CLI, Telegram, Discord, Slack, WhatsApp, and IDE workflows
  • Self-hosting: run locally, on a VPS, or in cloud infrastructure
  • Model flexibility: use OpenRouter or direct LLM providers
  • Extensibility: add plugins, tools, commands, and hooks

Hermes is useful if you want:

  • An AI pair programmer that can remember your codebase
  • A shared assistant for a team or workspace
  • Long-running automation through scheduled tasks
  • Data for training or evaluating custom agent behavior

Installation

Prerequisites

Before installing Hermes, make sure you have:

  • macOS, Linux, or Windows with WSL recommended
  • Python 3.10+
  • Git
  • An API key from OpenRouter, Anthropic, OpenAI, or another supported provider

Quick Install

Use the installer script:

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

The script:

  1. Clones the Hermes repository
  2. Installs uv
  3. Creates a Python virtual environment
  4. Installs dependencies
  5. Adds Hermes to your PATH

Reload your shell:

source ~/.bashrc  # bash
source ~/.zshrc   # zsh
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

hermes --version
Enter fullscreen mode Exit fullscreen mode

You should see output similar to:

Hermes Agent v0.5.0
Enter fullscreen mode Exit fullscreen mode

Manual Install

Use this path if you want to work on Hermes directly or control the environment yourself.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv venv --python 3.11
source venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

On Windows:

.\venv\Scripts\activate
Enter fullscreen mode Exit fullscreen mode

Install Hermes with all features:

uv pip install -e ".[all,dev]"
Enter fullscreen mode Exit fullscreen mode

Run tests:

python -m pytest tests/ -q
Enter fullscreen mode Exit fullscreen mode

Install RL Training Support

If you plan to train custom models, initialize the training submodule and install its dependencies:

git submodule update --init tinker-atropos
uv pip install -e "./tinker-atropos"
Enter fullscreen mode Exit fullscreen mode

Initial Setup

Run the Setup Wizard

For first-time setup, use:

hermes setup
Enter fullscreen mode Exit fullscreen mode

The wizard helps you configure:

  • LLM provider
  • API keys
  • Persistent memory
  • Terminal backend
  • Optional gateways such as Telegram, Discord, or Slack

Manual Configuration

Open the config file:

hermes config edit
Enter fullscreen mode Exit fullscreen mode

Or set values directly:

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend local
hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set ANTHROPIC_API_KEY sk-ant-...
Enter fullscreen mode Exit fullscreen mode

Hermes stores API keys in:

~/.hermes/.env
Enter fullscreen mode Exit fullscreen mode

Do not commit or share this file.

Configuration Directory

Hermes stores local data under ~/.hermes/:

~/.hermes/
├── config.yaml      # Main configuration
├── .env             # API keys
├── memory/          # Persistent memory storage
├── skills/          # Installed skills
└── plugins/         # Custom plugins
Enter fullscreen mode Exit fullscreen mode

Verify Your Setup

Run:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

This checks:

  • Config validity
  • API key connectivity
  • Memory status
  • Gateway status
  • Terminal backend connection

Choose an LLM Provider

Hermes can work with multiple model providers. Pick the provider based on cost, privacy, context length, and coding quality requirements.

OpenRouter

OpenRouter is a good default because one API key gives access to many models.

hermes config set model openrouter
hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

Example model choices:

Model Use case Relative cost
anthropic/claude-opus-4 Complex coding and reasoning High
anthropic/claude-sonnet-4 Balanced development work Medium
openai/gpt-4o General-purpose tasks Medium
google/gemini-pro-1.5 Long-context workflows Low
meta/llama-3-70b Open-source, fast tasks Low

Anthropic Direct

Use Anthropic directly if you want direct access to Claude models.

hermes config set model anthropic
hermes config set ANTHROPIC_API_KEY sk-ant-...
hermes config set model.default claude-opus-4
Enter fullscreen mode Exit fullscreen mode

OpenAI Direct

Use OpenAI directly for GPT-4o or o1 workflows.

hermes config set model openai
hermes config set OPENAI_API_KEY sk-...
Enter fullscreen mode Exit fullscreen mode

Local Models with Ollama

Use Ollama if you want local, private, offline-capable inference.

hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Install Ollama first from:

https://ollama.ai
Enter fullscreen mode Exit fullscreen mode

Example Model Config

Smart routing with fallbacks:

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

Budget controls:

model:
  budget:
    daily_limit: 5.00
    monthly_limit: 100.00
Enter fullscreen mode Exit fullscreen mode

Basic CLI Usage

Start Hermes:

hermes
Enter fullscreen mode Exit fullscreen mode

Then chat naturally:

> Help me write a Python function to parse JSON safely.
Enter fullscreen mode Exit fullscreen mode

Useful Slash Commands 

> /help       # Show commands
> /skills     # Browse skills
> /memory     # View memory status
> /config     # View or edit config
> /clear      # Clear current conversation
> /history    # View past conversations
Enter fullscreen mode Exit fullscreen mode

Work with Files

Ask Hermes to inspect a file:

> Look at ./src/main.py and explain the database connection flow.
Enter fullscreen mode Exit fullscreen mode

Ask it to edit a file:

> In main.py, change the database port from 5432 to 5433.
Enter fullscreen mode Exit fullscreen mode

Create a new file:

> Create utils.py with helper functions for date formatting.
Enter fullscreen mode Exit fullscreen mode

Run Terminal Commands

You can ask Hermes to run commands:

> Run: npm install && npm run build
Enter fullscreen mode Exit fullscreen mode

Hermes asks for confirmation before executing commands.

Use a Persistent Shell

Hermes keeps shell state across commands:

> cd /my/project && source venv/bin/activate
> python src/main.py
Enter fullscreen mode Exit fullscreen mode

The virtual environment remains active for later commands in the same shell session.

Run Multi-Step Development Tasks

Example:

> Add user authentication to my Flask app:
> 1. Create database models
> 2. Add login and logout endpoints
> 3. Generate JWT tokens
> 4. Write tests for the auth flow
Enter fullscreen mode Exit fullscreen mode

Hermes can break the task into steps and ask for confirmation as it works.

Messaging Gateways

Hermes can run as a bot in messaging platforms so you can use it from your phone or team chat.

Telegram Setup

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow the prompts
  4. Copy the bot token

Configure Hermes:

hermes config set TELEGRAM_BOT_TOKEN 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Enter fullscreen mode Exit fullscreen mode

Start the gateway:

hermes gateway setup telegram
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Then open your bot in Telegram, send /start, and chat.

Discord Setup

  1. Go to https://discord.com/developers/applications
  2. Create a new application
  3. Open the Bot section
  4. Create a bot and copy the token
  5. Use OAuth2 → URL Generator to invite the bot to your server

Configure Hermes:

hermes config set DISCORD_BOT_TOKEN MTIzNDU2...
hermes gateway setup discord
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Use it by mentioning the bot:

@Hermes help me write a function that validates email addresses
Enter fullscreen mode Exit fullscreen mode

You can also use it in DMs.

Slack Setup

  1. Go to https://api.slack.com/apps
  2. Create a new app from scratch
  3. Add bot permissions
  4. Install the app to your workspace
  5. Copy the bot token

Configure Hermes:

hermes config set SLACK_BOT_TOKEN xoxb-...
hermes gateway setup slack
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Run All Gateways

To start every configured gateway:

hermes gateway start --all
Enter fullscreen mode Exit fullscreen mode

Hermes syncs conversation state across platforms.

IDE Integration

Hermes integrates with editors through the Agent Communication Protocol.

VS Code

  1. Open Extensions with Ctrl+Shift+X
  2. Search for Agent Communication Protocol
  3. Install the extension
  4. Start the Hermes ACP server: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode

Then open the ACP sidebar, select Hermes, and chat from the editor.

JetBrains IDEs

For IntelliJ, PyCharm, and other JetBrains IDEs:

  1. Open Settings → Plugins
  2. Search for ACP or Agent Communication Protocol
  3. Install the plugin
  4. Restart the IDE
  5. Start Hermes: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode

Then configure Hermes under:

Settings → Tools → AI Agents
Enter fullscreen mode Exit fullscreen mode

Zed

Configure Zed:

{
  "agent": {
    "provider": "acp",
    "endpoint": "hermes"
  }
}
Enter fullscreen mode Exit fullscreen mode

Start Hermes:

hermes acp start
Enter fullscreen mode Exit fullscreen mode

Memory and Learning

Hermes uses memory to make future sessions more useful.

Memory Types

Type Purpose
Episodic memory Stores conversations and sessions
Semantic memory Builds knowledge about projects, preferences, and patterns
Procedural memory Stores reusable skills and workflows

Search memory:

> /memory search "database migration"
Enter fullscreen mode Exit fullscreen mode

List project memory:

> /memory projects
Enter fullscreen mode Exit fullscreen mode

List skills:

> /skills list
Enter fullscreen mode Exit fullscreen mode

Search Past Sessions

Example:

> /memory search "How did we handle JWT expiration last week?"
Enter fullscreen mode Exit fullscreen mode

Hermes searches prior context and summarizes relevant results.

Memory Nudges

Hermes can surface related context while you work:

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

Context Compression

Hermes automatically compresses context to avoid hitting model limits:

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

This helps keep long conversations usable without manual pruning.

Backup and Restore Memory

Export memory:

hermes memory export ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Import memory:

hermes memory import ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Skills and Plugins

Skills

Skills are reusable workflows Hermes can execute.

Built-in examples include:

  • code_review
  • debug_session
  • api_tester
  • git_workflow
  • documentation

List skills:

> /skills list
Enter fullscreen mode Exit fullscreen mode

Install a skill:

> /skills install code_review
Enter fullscreen mode Exit fullscreen mode

Run a skill:

> /skills run code_review ./src/auth.py
Enter fullscreen mode Exit fullscreen mode

Create a Custom Skill

Create a file under ~/.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"
Enter fullscreen mode Exit fullscreen mode

Plugins

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

Example custom tool:

# ~/.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"}
Enter fullscreen mode Exit fullscreen mode

Plugin types:

  • Tools: new capabilities the agent can use
  • Commands: new slash commands
  • Hooks: before/after turn handlers

Advanced Workflows

Cron Scheduling

Ask Hermes to create a scheduled task:

> Set up a daily digest of my GitHub notifications at 9am.
Enter fullscreen mode Exit fullscreen mode

Or configure a task manually:

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

Subagent Delegation

Hermes can spawn subagents for parallel work.

Example:

> Review all PRs in my repo and summarize the changes.
Enter fullscreen mode Exit fullscreen mode

Hermes can delegate work to multiple subagents and synthesize the results.

Voice Mode

Start CLI voice mode:

hermes --voice
Enter fullscreen mode Exit fullscreen mode

Messaging platforms can also support voice-note workflows:

  • Send a voice message
  • Hermes transcribes it
  • Hermes responds in the chat

For Discord voice channels, Hermes can join and handle real-time voice interaction.

Browser Control

Hermes can integrate with Browser Use CLI 2.0 for web automation.

Example:

> Go to github.com and find the top 5 trending Python repos.
Enter fullscreen mode Exit fullscreen mode

Connect to a live Chrome instance with CDP:

hermes browser connect --cdp
Enter fullscreen mode Exit fullscreen mode

MCP Integration

Hermes supports Model Context Protocol servers.

Example config:

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

Worktree Mode

Run Hermes in an isolated Git worktree:

hermes -w
Enter fullscreen mode Exit fullscreen mode

This lets multiple agents work on the same repo concurrently without conflicting changes.

Run Other Agents Inside Hermes

You can ask Hermes to call another specialized agent:

> Use claude-code to review this pull request.
Enter fullscreen mode Exit fullscreen mode

This is useful when a subagent is better suited for a specific task.

Troubleshooting

API Key Not Found

Check whether the key is set:

hermes config get OPENROUTER_API_KEY
Enter fullscreen mode Exit fullscreen mode

Set it again if needed:

hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

Model Not Available

List available models:

hermes models list
Enter fullscreen mode Exit fullscreen mode

Change the model:

hermes config set model anthropic/claude-opus-4
Enter fullscreen mode Exit fullscreen mode

Gateway Failed to Start

Check status:

hermes gateway status
Enter fullscreen mode Exit fullscreen mode

Restart:

hermes gateway stop
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Memory Corruption Detected

Back up memory first:

hermes memory export ~/backup/memory-backup.json
Enter fullscreen mode Exit fullscreen mode

Reset memory:

hermes memory reset
Enter fullscreen mode Exit fullscreen mode

Re-import if needed:

hermes memory import ~/backup/memory-backup.json
Enter fullscreen mode Exit fullscreen mode

Get Help

Inside Hermes:

> /help
Enter fullscreen mode Exit fullscreen mode

View logs:

hermes logs tail --follow
Enter fullscreen mode Exit fullscreen mode

Run diagnostics:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

FAQ

How much does Hermes cost?

Hermes itself is free. You pay for LLM usage.

Typical monthly ranges:

  • Light use: $5–15
  • Moderate development use: $20–50
  • Heavy automation: $50–200

Local models through Ollama can avoid API usage costs but require suitable hardware.

Can Hermes run 24/7?

Yes. For example, on a VPS:

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

hermes service install
hermes service start
Enter fullscreen mode Exit fullscreen mode

Is Hermes suitable for enterprise use?

Hermes includes features relevant to enterprise deployments, including:

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

How do I migrate from OpenClaw?

Preview the migration:

hermes claw migrate --dry-run
Enter fullscreen mode Exit fullscreen mode

Run it:

hermes claw migrate
Enter fullscreen mode Exit fullscreen mode

Verify the result:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

Can I use Hermes without internet?

Yes, with local models.

Install Ollama:

curl -fsSL https://ollama.ai/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Pull a model:

ollama pull qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Configure Hermes:

hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Hermes vs. ChatGPT

Feature Hermes ChatGPT
Memory Persistent and searchable Session-only
Deployment Self-hosted, can run 24/7 Cloud-only
Model choice 200+ models GPT models
Extensibility Plugins and skills Limited
Cost model Pay for usage Subscription
Privacy You control deployment and data OpenAI stores data

How do I back up all Hermes data? 

hermes export --all ~/backup/hermes-full-backup.tar.gz
Enter fullscreen mode Exit fullscreen mode

Can Hermes access my local files?

Hermes can access files you explicitly reference or directories you grant permission to. By default, it does not have unrestricted filesystem access.

Want to include API testing in your AI-assisted development workflow? Use Apidog to design, test, and document APIs alongside your agent-based coding process.

Top comments (0)