Hermes
Two jobs for AI: write software to do jobs — or use software to do jobs better (lowest cost, best quality, no waste). Hermes lives on the second side of that line.
Two roles, same agent: internal courier (carrying intent between systems) and external receiver (catching what's emerging in the marketplace). It runs autonomous transactions — the agent that carries intent across systems without a human relay. At the system level, Hermes is also the reception layer: the agent that watches external signals (tool releases, research papers, changelog feeds) and surfaces what's arriving before the window closes.
But you do not start with orchestration. You start with a browser. This guide walks the ladder — from zero setup to a background operator running autonomous jobs. Each step compounds the last. Skip nothing.
The Onboarding Ladder
| Step | Tool | What You Can Do | Setup |
|---|---|---|---|
| 1. Ask | Perplexity in browser | Research, plan, explore | Zero — open a tab |
| 2. Act | Claude Code in terminal | Read, write, and run code in your repo | 30 minutes |
| 3. Orchestrate | Hermes Agent on VPS | Schedule, remember, delegate, compound | 1 hour |
Each step adds a plane of capability. Step 1 is intelligence. Step 2 is agency with hands. Step 3 is a system that runs while you sleep.
Step 1: Ask
Open Perplexity in your browser. Type anything.
This is the base layer: access to an LLM with web search, reasoning, and structured output. No install. No account setup beyond email. You can research, draft, plan, and explore immediately.
First Questions
Ask something real. Not "what can you do?" — a question you actually need answered today:
- "What are the top three open-source AI agent frameworks released in 2026, and how do they compare on memory persistence?"
- "Draft a one-page brief on how Nx solves monorepo dependency management vs Turborepo"
- "Research the current state of MCP servers for GitHub integration"
Prompt Hygiene
Before you install anything, get good at asking. The quality of your prompts determines the quality of every agent downstream. See Prompt Library for structured patterns.
Move to Step 2 when you are tired of copy-pasting answers into your codebase, or repeating the same instructions every time you open a chat.
Step 2: Act
See Claude Code Onboarding for the full install. Compressed:
curl -fsSL https://claude.ai/install.sh | bash
claude
Claude Code has hands — it reads your files, writes code, runs commands, and commits. It is the craftsman at the terminal.
Setup checklist:
- CLAUDE.md — project instructions loaded every session
- Rules — always-enforced constraints in
.claude/rules/ - Skills — reusable workflows invoked with slash commands
Move to Step 3 when you find yourself asking Claude Code to do the same monitoring, summarization, or research tasks repeatedly — or when you want something running overnight without you present.
Step 3: Orchestrate
Claude Code is the craftsman. Hermes is the butler that never forgets, never sleeps, and keeps improving its own job description.
Install
Linux or Mac (or WSL2 on Windows):
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh
hermes setup
Walks you through:
- LLM provider — OpenRouter, Nous Portal, OpenAI, or local (Ollama)
- Default model — Claude Sonnet 4 recommended. Switch anytime with
/model - Terminal backend — Local, Docker (isolated), or SSH/Modal/Daytona (remote)
Start it:
hermes
Connect the Gateway
The CLI is the door. The gateway is the room.
hermes gateway setup
For Telegram (fastest): message @BotFather, send /newbot, copy the token, paste it when prompted.
hermes gateway install
Now Hermes is always on — reachable from your phone via Telegram, your desk via CLI, your team via Discord or Slack. Same brain, different doors.
Enable Learning
Critical: Honcho (dialectical user modeling) is off by default. Enable it in ~/.hermes/config.yaml or the agent will not self-improve. This is the most common reason new users think "memory is not working."
Skills follow the agentskills.io open standard:
hermes skills browse # interactive browser
hermes skills search <topic> # keyword search
hermes skills info <name> # inspect before installing
Always verify the trust tier (Builtin, Official, Trusted, Community) before installing. For Community tier, read the source first.
First Memory
Tell Hermes what matters:
Remember: I run an Nx monorepo. Never suggest monolith patterns.
Remember: Conventional commits with scope prefix. Always.
Remember: For [your-project-name], deliver research briefs on Telegram at 8am daily.
Hermes writes this to persistent memory (~/.hermes/MEMORY.md). Every session loads it. You never repeat yourself.
First Skill
Skills are the asset. Each one is a markdown file encoding a procedure, pitfalls, and verification steps.
Can you create a Skill called "nx-hex-architecture" that enforces our module
boundary conventions — libraries in libs/, apps in apps/, no cross-dependencies
between same-level modules, and all shared code goes through the core layer?
Hermes creates ~/.hermes/skills/nx-hex-architecture/SKILL.md. It auto-loads on future relevant tasks. It improves the Skill when you give corrective feedback.
First Cron Job
The real unlock: autonomous jobs that run without you.
Every weekday at 8am NZT, scan my GitHub repos for new PRs and issues.
Send me a Telegram summary with priority tags. Review any PRs against my
code review standards.
Hermes schedules it. Runs it. Delivers results to Telegram while you have breakfast.
What Compounds Over Time
| Layer | What Happens | Timeline |
|---|---|---|
| Memory | Remembers your preferences, rejected approaches, project context | Day 1 |
| Skills | Auto-creates Skills after complex tasks (5+ tool calls); improves them with your feedback | Week 1 |
| FTS5 Recall | Searches past sessions on-demand — pulls specific details, not bulk dumping | Week 1 |
| Cron Jobs | Background monitoring, reporting, research delivery | Day 1 |
| Honcho | Infers your work patterns, communication style, technical level across 12 layers | Month 1 |
| Sub-Agent Delegation | Parallel research: 3 concurrent agents with isolated contexts | When needed |
Capabilities
Hermes is model-agnostic (18+ LLM providers), multi-platform (Telegram, Slack, Discord, CLI, and 14+ messaging platforms), and ships with 47 built-in tools plus access to 643+ skills.
| Capability | What it does | When to use |
|---|---|---|
| Persistent memory | Cross-session MEMORY.md + USER.md injected at start | Accumulating workflow rules, preferences, lessons |
| Cron scheduling | Isolated sessions firing on schedule | Monitoring feeds, follow-up drafts, daily briefings |
| Parallel delegation | Up to 3 concurrent subagents, depth limit 2 | Research workstreams, competitive analysis |
| Speech-to-text | Whisper (local, 99 languages, no API key) | Meeting transcription |
| Feed monitoring | blogwatcher + RSS/Atom | Industry signals, competitor tracking |
| Research | arxiv, polymarket, web_search, web_extract | Pre-meeting briefs, industry analysis |
| Workspace integration | Gmail, Calendar, Drive, Sheets via OAuth2 | Draft emails, calendar management |
| Live model switching | /model command changes model mid-session | Cost management, task-specific model selection |
| Background notify | notify_on_complete pings you when a job finishes | Long-running cron jobs, async research |
| Skills hub | hermes skills browse — 643+ community skills | Installing purpose-built procedures on demand |
Critical constraint: Cron jobs run in fresh sessions with no conversational memory. Prompts must be completely self-contained — include all file paths, context, and instructions explicitly.
Bounded memory is a design choice. MEMORY.md (2,200 chars) and USER.md (1,375 chars) are deliberately capped. The constraint forces consolidation: the agent must decide what is worth keeping, which produces tighter priors than unbounded memory. For long-term semantic memory, eight external providers (Hindsight, Honcho, Mem0, and others) plug in on top of the default SQLite layer.
Two-Agent System
Hermes and Claude Code divide work by boundary: Hermes crosses into the external world; Claude Code operates inside the repo.
Hermes — watches the world (blogs, feeds, research papers), runs while you sleep via cron, produces structured files in a shared working directory, and serves as the external reception layer.
Claude Code — acts on the repo (docs, PRDs, plans), runs in active sessions, reads Hermes output and turns it into repo artifacts, and serves as the internal action layer.
The handoff is the filesystem. Hermes writes structured notes and research to a shared working directory. Claude Code picks them up on the next session and converts them into PRDs, industry analyses, or doc updates.
The Two Jobs
Write software to do jobs — Hermes spawns sub-agents that research, draft, and verify. Delegates coding work to Claude Code with structured instructions. Skills encode the "how" so it never forgets.
Use software to do jobs effectively — Hermes connects to external services via MCP (GitHub, databases, email, calendars). Schedules monitoring with cron. Delivers filtered intelligence — not noise — to your messaging apps. Reduces manual steps to zero.
The test for any Hermes job: lowest cost, best quality, no waste. If a job costs more in API tokens than the value it produces, the prompt is wrong or the scope is too broad. Shrink it.
Context
- Claude Code Onboarding — Step 2: LLM with hands on your files
- AI Agents — the category Hermes belongs to
- Agentic Workflows — the orchestration layer above individual agents
- Work Charts — the templates Hermes executes
- Evolution — the loop Hermes's reception role feeds
- AI Tools — the catalogue Hermes helps keep current
- Skills — modular workflows that encode the how
- Prompts — structured prompt patterns
Links
- Official Guide
- Hermes Atlas — Ecosystem Map — 100+ community repos, quality-filtered
- Hermes Atlas Guide — beginner's handbook
- State of Hermes April 2026
- Orange Book
- Complete Guide
- agentskills.io — open standard for cross-platform agent skills
- Nous Portal — single subscription for all supported models
Questions
At which step on the ladder are you spending most of your time — and is it the right step for the job you are trying to do?
- What manual process you do weekly could Hermes run overnight and deliver via Telegram?
- What type of task is Hermes best suited to run without human confirmation — and where does that boundary break down?
- When a cron job runs in an isolated session with no memory of prior context, what is the minimum information it needs to produce useful output?
- How does Hermes's skill creation loop compound differently from a human learning the same procedure?
- At what point does the two-agent system create coordination overhead that exceeds the value of specialisation?