hermes-agent

1---2name: hermes-agent3description: "Use, configure, theme, extend, and orchestrate Hermes Agent."4version: 3.2.05author: Hermes Agent + Teknium6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, bots, bot-mode, features, themes, skins, desktop-plugins, tui-widgets, petdex, development]11    homepage: https://github.com/NousResearch/hermes-agent12    related_skills: [claude-code, codex, opencode]13---14 15# Hermes Agent16 17Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.18 19What makes Hermes different:20 21- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.22- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.23- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.24- **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).25- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.26- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.27- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.28 29**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.30 31**Docs:** https://hermes-agent.nousresearch.com/docs/32 33## Scope & Verification34 35This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.36 37Good verification targets, cheapest first:38 39- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.40- CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`41- Source tree: https://github.com/NousResearch/hermes-agent42 43Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable.44 45## Quick Start46 47```bash48# Install (shell installer — sets up uv, Python, the venv, and the launcher)49curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash50 51# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)52hermes53 54# Single query55hermes chat -q "What is the capital of France?"56 57# Setup wizard  /  pick model+provider  /  health check58hermes setup59hermes model60hermes doctor61 62# Other surfaces63hermes desktop                 # launch the native desktop app (alias: hermes gui)64hermes dashboard               # web admin panel + embedded chat65hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider66```67 68## Key Paths69 70```71~/.hermes/config.yaml       Main configuration (settings — never secrets)72~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)73$HERMES_HOME/skills/        Installed skills74~/.hermes/skins/            Custom themes (see references/themes.md)75~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)76~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)77~/.hermes/pets/             Installed pet mascots (see references/petdex.md)78~/.hermes/state.db          Canonical session store (SQLite + FTS5)79~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts80~/.hermes/logs/             Gateway and error logs81~/.hermes/auth.json         OAuth tokens and credential pools82~/.hermes/hermes-agent/     Source code (if git-installed)83```84 85Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.86 87## Routing Table — load the reference for the task88 89| User wants... | Load |90|---|---|91| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** |92| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |93| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |94| In-session slash commands | `references/slash-commands.md` |95| Provider setup, API keys, OAuth | `references/providers-and-models.md` |96| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |97| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |98| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |99| Delegation, cron, curator, kanban | `references/background-systems.md` |100| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |101| Webhook routes and event-driven runs | `references/webhooks.md` |102| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |103| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |104| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |105| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |106| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |107| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |108| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |109| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |110| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |111| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |112 113The reference list above is not the feature list — it is the set of topics that114need more than their docs page. For everything else Hermes ships, fetch115`llms.txt` and it maps the question to the page that answers it.116 117Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.118 119## Spawning Additional Hermes Instances120 121Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.122 123### When to Use This vs delegate_task124 125| | `delegate_task` | Spawning `hermes` process |126|-|-----------------|--------------------------|127| Isolation | Separate conversation, shared process | Fully independent process |128| Duration | Minutes (bounded by parent loop) | Hours/days |129| Tool access | Subset of parent's tools | Full tool access |130| Interactive | No | Yes (PTY mode) |131| Use case | Quick parallel subtasks | Long autonomous missions |132 133### One-Shot Mode134 135```136terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)137 138# Background for long tasks:139terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)140```141 142### Interactive PTY Mode (via tmux)143 144Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:145 146```147# Start148terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)149 150# Wait for startup, then send a message151terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)152 153# Read output154terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)155 156# Send follow-up157terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)158 159# Exit160terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)161```162 163### Multi-Agent Coordination164 165```166# Agent A: backend167terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)168terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)169 170# Agent B: frontend171terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)172terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)173 174# Check progress, relay context between them175terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)176terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)177```178 179### Session Resume180 181```182# Resume most recent session183terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)184 185# Resume specific session186terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)187```188 189### Tips190 191- **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process192- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts193- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes194- **Use `hermes chat -q` for fire-and-forget** — no PTY needed195- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit196- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry197- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."198- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).199 200## Surfaces (quick orientation)201 202- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.203- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.204- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.205- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.206 207## Hard Invariants (never violate, regardless of what you loaded)208 209- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.210- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.211- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.212- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.213- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.214