Hermes Bots — The Definitive Guide

Hermes Agent is the only AI agent with a built-in learning loop — it creates skills from experience, improves them during use, and builds a deepening model of you across sessions. Built by Nous Research, it runs anywhere: your laptop, a $5 VPS, a GPU cluster, or serverless infrastructure.

This guide covers Bot Mode — turning Hermes profiles into named, persistent bots that run routines, deliberate together, and message each other directly.

Installation & Setup

Quick Start

Hermes Agent installs in under a minute. Choose your path:

Command-line only install

$ hermes setup

$ hermes
> Hello! I'm Hermes, your self-improving AI agent.

System Requirements

Profiles — Isolated Agent Instances

What are profiles?

A profile is a complete, isolated Hermes installation with its own config, API keys, personality, memory, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing state.

Directory Structure

~/.hermes/
├── config.yaml        # Settings (model, terminal, tools, memory, compression)
├── .env               # API keys and secrets (NEVER in config.yaml)
├── auth.json          # OAuth credentials (Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── AGENTS.md          # Project-specific instructions (auto-injected)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/           # Gateway session state
├── checkpoints/       # Filesystem snapshots (for /rollback)
├── logs/              # agent.log, gateway.log, errors.log
└── state.db           # Session store (SQLite + FTS5)

Creating a Profile

$ hermes profile create coder --description "Full-stack coding assistant"

$ coder setup --portal

$ coder chat

Cloning Profiles

# Clone config + SOUL + skills (fresh memory/sessions)
$ hermes profile create work --clone

# Clone everything including memories + cron
$ hermes profile create backup --clone-all

# Clone from a specific profile
$ hermes profile create work --clone-from coder

# Publish a profile as a git distribution
$ hermes profile install github.com/you/research-bot --alias
$ hermes profile update research-bot  # pull updates, keeps your data

Profile Commands

How Profiles Work

Profiles use the HERMES_HOME environment variable. Running coder chat sets HERMES_HOME=~/.hermes/profiles/coder. The wrapper script handles this — you never need to set it manually.

Bot Mode — Building Your Bot Fleet

What is Bot Mode?

Bot Mode turns your Hermes profiles into a roster of named Bots. Each Bot has its own role, model, memory, skills, and avatar; Bots run recurring routines, deliberate together in group chats, and message each other directly. Build a specialist Bot once and it is there forever, one click away.

Bot Mode ships built into the Hermes Desktop app and is on by default. It appears as a Bots tab next to Sessions in the left sidebar, with a Routines tile docked beside the conversation.

The Bots Pane

The roster shows one row per agent profile: avatar, latest-message preview, and timestamp. Click a Bot to land in its chat — every Bot has a canonical, persistent Bot Chat conversation created the moment the Bot is born.

Creating a Bot

Bots Across Machines

Register multiple backends in Settings → Connections — local runtime, remote gateways, SSH hosts, Hermes Cloud. When you register peer gateways on other machines via hermes peer add …, the roster shows Bots from every connected source persistently. Unreachable machines keep their last-known rows instead of vanishing.

CLI Parity

Messaging Platforms (20+)

• Telegram, Discord, Slack, Signal, SMS/Twilio
• WhatsApp (Business Cloud API + Baileys bridge)
• iMessage (via Photon Spectrum — no Mac relay)
• Google Chat, SimpleX, Matrix, IRC, Microsoft Teams, Tencent Yuanbao
• Email gateway, Spotify (native via PKCE OAuth)

Skills — Procedural Memory That Improves

What are Skills?

Skills are procedural knowledge documents the agent loads on demand. They follow progressive disclosure to minimize token usage and are compatible with the agentskills.io open standard. All skills live in ~/.hermes/skills/.

Skill Types

Using Skills

Every installed skill is available as a slash 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
/plan design a rollout for migrating our auth provider

Stack multiple skills (up to 5):

/github-pr-workflow /test-driven-development fix issue #123 and open a PR

Learning with /learn

/learn turns anything you can describe into a reusable skill:

/learn the REST client in ~/projects/acme-sdk, focus on auth + pagination
/learn https://docs.example.com/api/quickstart
/learn how I just deployed the staging server

Large sources (books, paper stacks, specs) become knowledge-base skills: a lean SKILL.md with core mental models plus an index, one distilled file per chapter/topic under references/, and a glossary when the source earns one. Reference files cost nothing until a question needs one — the agent loads them on demand with skill_view, so query cost stays proportional to the answer, not the source.

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]
    requires_toolsets: [terminal]
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Skill Hub Commands

$ hermes skills browse                        # Browse all hub skills
$ hermes skills browse --source official    # Official catalog
$ hermes skills search kubernetes           # Search all sources
$ hermes skills inspect openai/skills/k8s   # Preview before install
$ hermes skills install openai/skills/k8s   # Install with security scan
$ hermes skills check                       # Check for updates
$ hermes skills update                      # Reinstall changed skills
$ hermes skills audit                       # Re-scan all skills
$ hermes skills uninstall k8s               # Remove

Hub Sources

• official — Nous Research optional skills catalog
• skills-sh — Community catalog (19,000+ entries)
• clawhub — OpenClaw marketplace
• lobehub — LobeHub skills
• github — Any GitHub repo with SKILL.md
• well-known — /.well-known/skills/ endpoints

The Curator

An autonomous background process that grades, prunes, and consolidates the skill library on a configurable cycle (default: 7 days):

$ hermes curator status     # Check status
$ hermes curator run        # Run now
$ hermes curator pause      # Pause auto-runs
$ hermes curator pin <skill>  # Pin so Curator won't prune it

Cron Jobs — Automated Routines

What are Cron Jobs?

Hermes includes a built-in cron scheduler for recurring, automated tasks. Jobs run with the full toolset, skills, and memory available. Output can be delivered to any connected messaging platform.

Creating a Cron Job

# Recurring job with skill loading + delivery
$ hermes cron create \
  --schedule "every 30m" \
  --prompt "Check our production API health and report if down" \
  --skills health-check \
  --deliver telegram:@your-bot

# One-shot scheduled job
$ hermes cron create \
  --schedule "2026-08-24T09:00:00" \
  --prompt "Run quarterly budget report and email results"

Schedule Formats

"30m"            → every 30 minutes
"every 2h"         → every 2 hours
"0 9 * * *"        → daily at 9 AM (cron syntax)
"2026-08-24T09:00" → one-shot ISO timestamp

Advanced Features

Cron Commands

$ hermes cron list                  # List all jobs
$ hermes cron create ...            # Create new
$ hermes cron run <id>             # Fire immediately
$ hermes cron pause <id>           # Pause
$ hermes cron resume <id>          # Resume
$ hermes cron update <id> ...     # Update
$ hermes cron remove <id>         # Delete

Script-Only Watchdog

#!/bin/bash
THRESHOLD=90
usage=$(df / | tail -1 | awk '{print $5}' | tr -d '%')
if [ "$usage" -gt "$THRESHOLD" ]; then
  echo "WARNING: Disk usage at ${usage}%"
fi

Messaging Gateways

What is a Gateway?

A Hermes gateway is a long-running process that routes messages from messaging platforms through the same conversation loop as the CLI. Each profile runs its own gateway as a separate process with its own bot token.

$ hermes gateway start

$ hermes gateway setup

$ hermes gateway status
$ hermes gateway install  # systemd (Linux) / launchd (macOS)

Per-Platform Setup

Application Examples

Scenario 1: Research Agent

A dedicated agent that monitors academic sources, summarizes findings, and archives knowledge.

Cron: Daily ArXiv Monitor

$ hermes cron create \
  --schedule "0 9 * * *" \
  --prompt "Search arxiv for new RLHF papers, summarize the top 5, append to Notion" \
  --skills arxiv-search,notion-write \
  --deliver notion:ResearchQueue

Scenario 2: Operations Bot

Attached to messaging channels with scheduled reports. Each profile runs its own gateway and bot token.

Cron: Hourly K8s Health Report

$ hermes cron create \
  --schedule "every 1h" \
  --prompt "Check kubernetes cluster health, summarize node status, post to #ops-alerts if any node is NotReady or CPU > 90%" \
  --skills kubernetes,slack-notify \
  --deliver discord:#ops-alerts

Scenario 3: Coding Assistant Fleet

Multiple bots collaborating on a single codebase — frontend, backend, and reviewer bots with complementary skills.

# Create the team
$ hermes profile create frontend --description "React/Vue specialist"
$ hermes profile create backend  --description "API + database engineer"
$ hermes profile create reviewer --description "Code review and security"

# All start with the same codebase context
$ frontend chat → /axolotl install react,typescript
$ backend chat  → /axolotl install python,sql,postgresql
$ reviewer chat → /axolotl install security-audit,github-code-review

Scenario 4: Personal AI Assistant

A persistent agent that learns your preferences, schedules, and workflows — survives across sessions via persistent memory.

Inside a profile, SOUL.md shapes the agent's personality, USER.md stores your preferences, and MEMORY.md accumulates lessons across sessions. The agent's state.db (SQLite + FTS5) enables cross-session recall — it remembers past conversations and summarizes them on demand rather than loading raw history.

Cron: Morning Briefing

$ hermes cron create \
  --schedule "0 8 * * *" \
  --prompt "Summarize today's calendar events, unread emails, and overdue tasks" \
  --skills google-workspace,apple-reminders \
  --deliver telegram:@personal-bot

Scenario 5: Content Pipeline Bot

End-to-end content: research → draft → humanize → design → publish. Stack skills to chain the full workflow.

Each skill in the chain loads in order: /youtube-content transcribes and summarizes a source, /humanizer strips AI-isms and adds natural voice, /claude-design packages it into a publishable layout.

Cron: Weekly Content Audit

$ hermes cron create \
  --schedule "0 10 * * 1" \
  --prompt "Find the top 5 performing posts from last week, summarize why they worked, and draft 3 new angles" \
  --skills airtable,google-workspace \
  --deliver notion:ContentIdeas

Scenario 6: Data Pipeline Monitor

Monitor data pipelines, alert on anomalies, and generate reports — using the watchdog pattern.

The --no-agent flag skips the LLM entirely — the script's stdout is delivered verbatim. Empty output means a silent tick (nothing sent), so the bot only alerts when something is actually wrong.

Agent-Driven Variant

$ hermes cron create \
  --schedule "every 1h" \
  --prompt "Query the production DB for failed jobs in the last hour, summarize root cause, and suggest a fix" \
  --skills terminal,github-issues \
  --deliver discord:#data-alerts

Appendix

Key Directory Paths

~/.hermes/                    # Default profile root
~/.hermes/profiles/<name>/  # Named profile
~/.hermes/config.yaml         # Main config (settings, never secrets)
~/.hermes/.env                # API keys and secrets
~/.hermes/auth.json           # OAuth provider credentials
~/.hermes/SOUL.md             # Primary agent identity
~/.hermes/memories/MEMORY.md  # Persistent memory (agent-written)
~/.hermes/memories/USER.md    # User preferences
~/.hermes/skills/             # All installed skills
~/.hermes/cron/               # Scheduled jobs
~/.hermes/sessions/           # Gateway session state
~/.hermes/logs/               # agent.log, gateway.log, errors.log
~/.hermes/state.db            # Session store (SQLite + FTS5)

Configuration Sample

model:
  default: anthropic/claude-sonnet-4
  provider: openrouter

agent:
  disabled_toolsets: ["browser"]
  max_turns: 500

terminal:
  backend: local             # local, docker, ssh, daytona, singularity, modal
  cwd: /home/user/projects

compression:
  threshold: 0.7            # 70% = caution, 90% = warning
  target_ratio: 0.3
  protect_last_n: 2

auxiliary:                    # Models for internal operations
  vision: openai/gpt-4o
  web_extract: openai/gpt-4o-mini
  compression: google/gemini-1.5-flash
  session_search: openai/gpt-4o-mini
  skills_hub: openai/gpt-4o-mini
  mcp: openai/gpt-4o-mini

CLI Quick Reference

Common Slash Commands

/learn      Turn anything into a reusable skill
/skill      Load a skill from within chat
/goal       Lock a target for cross-turn work
/journey    Visualize memory + skill timeline
/rollback   Undo to a filesystem checkpoint
/version    Show agent + model version
/billing    Show usage + cost breakdown
/update     Reload agent source files
/export     Export current profile to .tar.gz
/import     Import a profile archive

Terminal Backends

Useful Links