Quick answer: Hermes Agent is an open-source AI agent framework by Nous Research. Install it with curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash, then run hermes to launch. It works with any LLM provider (20+ supported), runs on Linux/macOS/Windows, and connects to Telegram, Discord, Slack, and 10+ messaging platforms. This article is the complete command reference — every CLI flag, slash command, toolset, config key, and workflow you’ll actually use.
I’ve been running Hermes Agent across three machines and five messaging platforms for the past few months. In that time, I’ve burned through the docs, filed bug reports, contributed patches, and built workflows that depend on it daily. The official docs are excellent but scattered — you end up with 20 browser tabs open trying to remember whether the flag is -w or --worktree. Here’s how I consolidated everything into a single reference I actually use.
What Is Hermes Agent and Why Does It Matter for AI-Native Development?
Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, on Telegram, Discord, Slack, and 10+ other messaging platforms — with full tool access, persistent memory, and self-improving skills. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw, but with three critical differences: it works with any LLM provider (20+ supported), it learns from experience by saving reusable procedures as skills, and it runs natively on Linux, macOS, and Windows.
Key stat: Hermes processes over 3,000 automated tool calls per active session — terminal commands, file operations, web searches, browser automation, and subagent delegation — all orchestrated through a single conversation loop with automatic context compression.
I first encountered Hermes while looking for an alternative to Claude Code that didn’t lock me into Anthropic’s ecosystem. The provider-agnostic model routing alone justified the switch — I can swap between OpenRouter, DeepSeek, local Ollama, or Gemini mid-workflow without touching config. Credential pools rotate across multiple API keys automatically, which eliminated the rate-limit headaches I’d hit with single-key setups.
What kept me was the skill system. After I solved a complex multi-agent orchestration problem, Hermes saved the entire workflow as a reusable skill document. Next time a similar task came up, it loaded that skill automatically. Over weeks, the agent accumulated domain knowledge about my projects, my preferences, and my environment. That’s the self-improvement loop that separates a real agent from a chat wrapper.
How Do You Install and Launch Hermes Agent?
Install Hermes with a single command. The installer handles Python virtual environment creation, dependency installation, and initial configuration scaffolding.
# Install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# Launch interactive chat (default)
hermes
# Single non-interactive query
hermes chat -q "Summarize the latest changes in this repo"
# Setup wizard (interactive configuration)
hermes setup
# Health check
hermes doctorOn Windows, Hermes runs natively in PowerShell, cmd, Windows Terminal, git-bash mintty, and VS Code integrated terminal. The terminal tool executes commands through bash (git-bash/MSYS), not PowerShell — use POSIX shell syntax inside terminal calls. If you hit the Alt+Enter issue where the terminal goes fullscreen instead of inserting a newline, use Ctrl+Enter instead.
What Configuration Files Control Hermes Agent Behavior?
Hermes uses two primary configuration files in ~/.hermes/: config.yaml for all behavioral settings (model, terminal, compression, delegation, tools) and .env for API keys and secrets. Edit configuration interactively with hermes config edit, or set individual values from the terminal:
# Open config in $EDITOR
hermes config edit
# Set individual values
hermes config set model.default anthropic/claude-sonnet-4
hermes config set compression.threshold 0.50
hermes config set agent.max_turns 90
# Print paths
hermes config path # ~/.hermes/config.yaml
hermes config env-path # ~/.hermes/.envThe core configuration sections that matter most:
| Section | Key Options | Default |
|---|---|---|
model | default, provider, base_url, api_key, context_length | Varies by provider |
agent | max_turns, tool_use_enforcement | 90 |
terminal | backend (local/docker/ssh/modal), cwd, timeout | 180s |
compression | enabled, threshold, target_ratio | 0.50 / 0.20 |
delegation | model, provider, max_iterations, reasoning_effort | 50 |
memory | memory_enabled, user_profile_enabled, provider | Built-in |
security | tirith_enabled, website_blocklist, redact_secrets | true |
Switch models interactively with hermes model, or set directly:
hermes model # Interactive picker
hermes config set model.default deepseek/deepseek-r1
hermes config set model.provider openrouterSupported providers include OpenRouter, Anthropic, OpenAI, DeepSeek, Google Gemini, xAI/Grok, Nous Portal, Xiaomi MiMo, Hugging Face, MiniMax, Kimi/Moonshot, Alibaba DashScope, and 10+ more. Each authenticates via environment variable (e.g., OPENROUTER_API_KEY, ANTHROPIC_API_KEY).
How Do Hermes Slash Commands Work Inside a Session?
Slash commands control the live session — model switching, tool management, skill loading, configuration, and session lifecycle. Type them directly in the interactive chat. Here are the ones I use daily, grouped by function:
Session Control
/new Start a fresh session (clears context)
/clear Clear screen and start new session (CLI)
/retry Resend the last message
/undo Remove the last exchange pair
/title <name> Name the current session
/compress Manually trigger context compression
/stop Kill all background processes
/rollback [N] Restore filesystem checkpoint
/agents Show active subagents and running tasks
/resume <name> Resume a named session
/goal <text> Set a standing goal across turnsThe /goal command is underrated — it sets a persistent objective that Hermes works toward across multiple turns until achieved. I use it for ongoing codebase refactors where I want the agent to keep context across interruptions.
Model and Configuration
/model <name> Show or change the active model
/personality <name> Set agent personality
/reasoning <level> Set reasoning depth (none|minimal|low|medium|high|xhigh)
/verbose Cycle verbosity: off → new → all → verbose
/yolo Toggle approval bypass for destructive commands
/config Display current configuration (CLI)Tool and Skill Management
/tools Manage toolsets interactively (CLI)
/skill <name> Load a specific skill into the current session
/skills Search and install skills (CLI)
/reload-skills Re-scan ~/.hermes/skills/ for changes
/reload Reload .env variables into the running session
/reload-mcp Reload MCP server connections
/cron Manage cron jobs (CLI)
/curator Skill lifecycle management (status, run, pin, archive)Gateway (Messaging Platforms)
/approve Approve a pending command (gateway)
/deny Deny a pending command (gateway)
/restart Restart the gateway service
/sethome Set current chat as home channel
/update Update Hermes to latest version
/platforms Show platform connection statusUtility
/branch Fork the current session
/fast Toggle priority processing
/browser Open CDP browser connection
/save Save conversation to file (CLI)
/copy [N] Copy last response to clipboard (CLI)
/usage Show token usage statistics
/help Display all available commandsWhat Tools Does Hermes Agent Provide and How Do You Enable Them?
Hermes exposes 30+ toolsets that give the agent access to your system, the web, file system, browser, and external services. Tools are discovered at startup and gated by check_fn requirements — a tool only appears if its dependencies are met. This is the core difference between a chatbot and an agent: Hermes can actually do things.
hermes tools # Interactive curses UI
hermes tools list # Show all tools and status
hermes tools enable browser
hermes tools disable image_genImportant: Tool changes take effect on
/reset(new session). They do NOT apply mid-conversation to preserve prompt caching.
The complete toolset inventory:
| Toolset | What It Does | When You’d Use It |
|---|---|---|
terminal | Shell commands, background processes, PTY mode | Build, install, git, servers |
file | Read, write, search, patch files | Code editing, config changes |
web | Web search and content extraction | Research, documentation lookup |
browser | Browser automation (CDP) | Form filling, screenshots, scraping |
code_execution | Sandboxed Python execution | Data processing, calculations |
vision | Image analysis | Chart reading, UI debugging |
image_gen | AI image generation | Mockups, diagrams |
video | Video analysis and generation | Content creation |
tts | Text-to-speech | Voice memos, accessibility |
skills | Skill browsing and management | Procedural knowledge loading |
memory | Persistent cross-session memory | Preferences, environment facts |
session_search | FTS5 search over past conversations | “What did we do about X?” |
delegation | Subagent task spawning | Parallel subtasks, long-running jobs |
cronjob | Scheduled task creation | Daily briefings, monitoring |
messaging | Cross-platform message sending | Notifications, alerts |
todo | In-session task planning | Multi-step workflows |
spotify | Spotify playback control | Music during work |
homeassistant | Smart home control | Lights, climate, automation |
kanban | Multi-agent work queue | Team coordination |
Connect external tools via MCP servers:
hermes mcp add my-server --url http://localhost:3000
hermes mcp list
hermes mcp test my-serverHow Does the Hermes Skill System Enable Self-Improvement?
Skills are Hermes’s procedural memory — reusable documents that encode how to perform specific tasks. When the agent solves a complex problem, discovers a workflow, or gets corrected, it persists that knowledge as a skill that loads into future sessions. I coined the term “context compounding” for this: each solved problem makes the agent measurably better at the next one, without retraining.
hermes skills list # Show installed skills
hermes skills search "trading strategy" # Search the skills hub
hermes skills install <skill-id> # Install from hub
hermes skills inspect <skill-id> # Preview without installingIn-session skill loading:
/skill github-pr-workflow # Load a specific skill
/reload-skills # Re-scan for newly added skillsEvery skill lives in ~/.hermes/skills/<category>/<name>/SKILL.md with YAML frontmatter:
---
name: my-workflow
description: "Reusable procedure for X"
tags: [devops, automation]
---
# My Workflow
## When to Use
...
## Steps
1. ...
2. ...The curator manages skill lifecycle automatically — tracking usage, marking idle skills stale, and archiving unused ones while keeping backups. It only touches agent-created skills; bundled and hub-installed skills are off-limits.
hermes curator status # View lifecycle state
hermes curator run # Trigger maintenance cycle
hermes curator pin <skill-name> # Protect from archival
hermes curator archive <skill-name> # Soft-archive unused skillSkills handle procedural memory — how to do things. But what about declarative memory — facts, preferences, environment details, lessons learned? That’s where the Hindsight memory system comes in. I wrote a full guide on how to wire up Hermes’s L1/L2 memory system so it doesn’t lose everything between sessions — covering Hindsight setup, embedding configuration, the retain/recall API, and the exact pitfalls that’ll wipe your memory bank if you’re not careful.
How Do You Spawn Subagents and Parallel Workers?
Hermes supports two delegation models, and the choice between them is one of the most important architectural decisions you’ll make. I think of it as the L1/L2 delegation split: L1 is quick, synchronous work inside your current turn; L2 is long-running autonomous work that persists independently.
delegate_task (Synchronous Subagent Spawn)
The subagent completes a task and returns a summary. The parent waits. Bounded duration, isolated context.
# Single subagent
delegate_task(
goal="Analyze this codebase for security vulnerabilities",
context="Focus on SQL injection and XSS in the API layer",
toolsets=["terminal", "file", "web"]
)
# Batch parallel (up to 3 concurrent)
delegate_task(tasks=[
{"goal": "Write unit tests for auth module", "toolsets": ["terminal", "file"]},
{"goal": "Research rate limiting best practices", "toolsets": ["web"]},
{"goal": "Generate API documentation", "toolsets": ["file", "web"]}
])Independent Process Spawning
Full hermes instances with complete tool access that run for hours or days. Use tmux for interactive PTY sessions.
# Fire-and-forget (no PTY needed)
hermes chat -q "Research GRPO training and write summary to ~/research/grpo.md"
# Interactive via tmux
tmux new-session -d -s agent1 -x 120 -y 40 'hermes'
sleep 8
tmux send-keys -t agent1 'Build a FastAPI auth service' Enter
# Multi-agent coordination
tmux new-session -d -s backend -x 120 -y 40 'hermes -w' # -w = worktree mode
tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'
tmux capture-pane -t backend -p | tail -30 # Check progress
# Resume previous session
hermes --continue # Most recent
hermes --resume 20260225_143052 # By session IDThe worktree flag (
-w) is critical when spawning agents that edit code — it creates an isolated git worktree so parallel agents don’t create merge conflicts. I learned this the hard way when two agents tried to edit the same file simultaneously.
How Do Hermes Cron Jobs Automate Recurring Tasks?
The cron system schedules durable, recurring agent tasks with multi-platform delivery. Unlike delegate_task (which dies with the parent), cron jobs persist across restarts.
# Create scheduled jobs
hermes cron create "0 9 * * *" --prompt "Summarize today's GitHub notifications"
hermes cron create "every 2h" --prompt "Check server health and alert on issues"
hermes cron create "30m" --prompt "Monitor RSS feeds for new research papers"
# Manage jobs
hermes cron list
hermes cron pause <job-id>
hermes cron resume <job-id>
hermes cron run <job-id> # Trigger immediately
hermes cron remove <job-id>
hermes cron statusAdvanced features that I use regularly:
| Feature | Syntax | Use Case |
|---|---|---|
| Chain jobs | context_from: ["job-a-id"] | Job A collects data, Job B processes it |
| Script-only mode | no_agent: true | Run a script, deliver stdout — no LLM tokens |
| Multi-platform delivery | deliver: "telegram:ID, discord:#channel" | Send to multiple destinations |
| Model override | model: {provider: "openrouter", model: "..."} | Use cheaper model for simple tasks |
| Working directory | workdir: "/path/to/project" | Load project-specific AGENTS.md |
How Does the Multi-Platform Gateway Work?
The gateway runs Hermes as a persistent service across messaging platforms — giving you full agent capabilities (tools, skills, browser, delegation) inside Telegram, Discord, Slack, WhatsApp, and 10+ other platforms. This is where I spend most of my time — having the agent accessible from my phone via Telegram means I can kick off research, check server status, or review code from anywhere.
hermes gateway setup # Configure platforms interactively
hermes gateway run # Start foreground
hermes gateway install # Install as background service
hermes gateway start # Start the service
hermes gateway stop # Stop the service
hermes gateway restart # Restart the service
hermes gateway status # Check statusSet your home channel (default delivery target for cron jobs and notifications):
/sethome # In any gateway-connected chatHow Do You Manage Sessions and Conversation History?
Hermes stores all sessions in a SQLite database at ~/.hermes/state.db with FTS5 full-text search. The session_search tool provides fast retrieval over past conversations — I use this constantly when picking up work from previous sessions.
hermes sessions list # Recent sessions
hermes sessions browse # Interactive picker
hermes sessions export output.jsonl # Export to JSONL
hermes sessions rename <id> "New Title" # Rename
hermes sessions delete <id> # Delete
hermes sessions prune --older-than 30 # Clean up
hermes sessions stats # Store statisticsWhat Are Profiles and How Do You Use Them?
Profiles run multiple independent Hermes instances with isolated configs, sessions, skills, and memory. Think of them as separate agent personas — a “work” profile with different tools and model settings than your “personal” profile.
hermes profile list # List all profiles
hermes profile create work # Create new profile
hermes profile create personal --clone # Clone current settings
hermes profile use work # Set sticky default
hermes profile show work # Show details
hermes profile delete work # Delete
hermes profile export work > work.tar.gz # Export
hermes profile import work.tar.gz # ImportEach profile lives at ~/.hermes/profiles/<name>/ with its own config.yaml, .env, skills/, and sessions/.
How Do You Troubleshoot Common Hermes Issues?
hermes doctor # Check dependencies and config
hermes doctor --fix # Auto-fix common issues
hermes status --all # Show all component statusThe most common issues and their fixes:
| Problem | Fix |
|---|---|
| Voice not working | hermes config set stt.enabled true + pip install faster-whisper |
| Tool not available | hermes tools list → enable → /reset |
| Model/provider error | hermes auth list → hermes auth add <provider> |
| Changes not taking effect | Tools/skills: /reset. Config: /restart. Code: relaunch CLI |
| Skills not showing | hermes skills list → hermes skills config → /skill <name> |
| Gateway crash loop | systemctl --user reset-failed hermes-gateway |
| UTF-8 BOM config error | Re-save config.yaml without BOM via hermes config edit |
The Takeaway
Hermes Agent is not a chatbot with tool calling bolted on — it’s a systems-level framework where tools, memory, skills, scheduling, and multi-agent orchestration are first-class citizens. The command surface is large (I count 60+ CLI commands and 37+ slash commands), but the actual mental model is simple: configure once, chat often, let skills accumulate.
The real power isn’t in any single command — it’s in the composition. A cron job triggers a script, which feeds data into a subagent, which writes findings to a file, which a skill references in a future session. That’s context compounding in action.
Build Your Own: Use This Article as a Starting Point
Paste this into Hermes and let it configure your environment:
“Set up Hermes Agent with OpenRouter as my provider, enable the terminal, file, web, browser, and skills toolsets, install the github-pr-workflow and code-review skills, and create a cron job that runs every morning at 9am to summarize my GitHub notifications and deliver them to my Telegram home channel.”
Hermes will walk through the entire setup — model configuration, tool enablement, skill installation, and cron scheduling — in a single session. That’s the agent doing what it does best: turning a one-sentence intent into a complete, working system.
What’s Next
This is the first in a series of deep dives into Hermes Agent. Next up: “How I Built a Multi-Agent Trading Pipeline with Hermes” — covering the orchestrator/worker architecture, cron-driven signal processing, real-time market data ingestion, and the delegation patterns that keep five parallel agents from stepping on each other.
If you found this reference useful, share it with someone who’s still copy-pasting commands from six different browser tabs. We’ve all been there.
Hermes Agent is open-source under the MIT license. Repository: github.com/NousResearch/hermes-agent. Documentation: hermes-agent.nousresearch.com/docs.
