# Hermes Agent ☤

**The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM. Use any model you want — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (200+ models), [NVIDIA NIM](https://build.nvidia.com) (Nemotron), [Xiaomi MiMo](https://platform.xiaomimimo.com), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), [Hugging Face](https://huggingface.co), OpenAI, or your own endpoint. Switch with `hermes model` — no code changes, no lock-in.

A real terminal interface	Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.
Lives where you do	Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.
A closed learning loop	Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. Honcho dialectic user modeling. Compatible with the agentskills.io open standard.
Scheduled automations	Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.
Delegates and parallelizes	Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.
Runs anywhere, not just your laptop	Six terminal backends — local, Docker, SSH, Daytona, Singularity, and Modal. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.
Research-ready	Batch trajectory generation, Atropos RL environments, trajectory compression for training the next generation of tool-calling models.

--- ## Quick Install ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the platform-specific setup for you. > **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies. > > **Windows:** Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command above. After installation: ```bash source ~/.bashrc # reload shell (or: source ~/.zshrc) hermes # start chatting! ``` --- ## Getting Started ```bash hermes # Interactive CLI — start a conversation hermes model # Choose your LLM provider and model hermes tools # Configure which tools are enabled hermes config set # Set individual config values hermes gateway # Start the messaging gateway (Telegram, Discord, etc.) hermes setup # Run the full setup wizard (configures everything at once) hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw) hermes update # Update to the latest version hermes doctor # Diagnose any issues ``` 📖 **[Full documentation →](https://hermes-agent.nousresearch.com/docs/)** ## CLI vs Messaging Quick Reference Hermes has two entry points: start the terminal UI with `hermes`, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces. | Action | CLI | Messaging platforms | |---------|-----|---------------------| | Start chatting | `hermes` | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message | | Start fresh conversation | `/new` or `/reset` | `/new` or `/reset` | | Change model | `/model [provider:model]` | `/model [provider:model]` | | Set a personality | `/personality [name]` | `/personality [name]` | | Retry or undo the last turn | `/retry`, `/undo` | `/retry`, `/undo` | | Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]` | | Browse skills | `/skills` or `/` | `/` | | Interrupt current work | `Ctrl+C` or send a new message | `/stop` or send a new message | | Platform-specific status | `/platforms` | `/status`, `/sethome` | For the full command lists, see the [CLI guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) and the [Messaging Gateway guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging). --- ## Documentation All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**: | Section | What's Covered | |---------|---------------| | [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes | | [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions | | [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options | | [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant | | [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Command approval, DM pairing, container isolation | | [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ tools, toolset system, terminal backends | | [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Procedural memory, Skills Hub, creating skills | | [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Persistent memory, user profiles, best practices | | [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Connect any MCP server for extended capabilities | | [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Scheduled tasks with platform delivery | | [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Project context that shapes every conversation | | [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | Project structure, agent loop, key classes | | [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Development setup, PR process, code style | | [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | All commands and flags | | [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference | --- ## Migrating from OpenClaw If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys. **During first-time setup:** The setup wizard (`hermes setup`) automatically detects `~/.openclaw` and offers to migrate before configuration begins. **Anytime after install:** ```bash hermes claw migrate # Interactive migration (full preset) hermes claw migrate --dry-run # Preview what would be migrated hermes claw migrate --preset user-data # Migrate without secrets hermes claw migrate --overwrite # Overwrite existing conflicts ``` What gets imported: - **SOUL.md** — persona file - **Memories** — MEMORY.md and USER.md entries - **Skills** — user-created skills → `~/.hermes/skills/openclaw-imports/` - **Command allowlist** — approval patterns - **Messaging settings** — platform configs, allowed users, working directory - **API keys** — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs) - **TTS assets** — workspace audio files - **Workspace instructions** — AGENTS.md (with `--workspace-target`) See `hermes claw migrate --help` for all options, or use the `openclaw-migration` skill for an interactive agent-guided migration with dry-run previews. --- ## Contributing We welcome contributions! See the [Contributing Guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) for development setup, code style, and PR process. Quick start for contributors — clone and go with `setup-hermes.sh`: ```bash git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent ./setup-hermes.sh # installs uv, creates venv, installs .[all], symlinks ~/.local/bin/hermes ./hermes # auto-detects the venv, no need to `source` first ``` Manual path (equivalent to the above): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh uv venv venv --python 3.11 source venv/bin/activate uv pip install -e ".[all,dev]" scripts/run_tests.sh ``` > **RL Training (optional):** The RL/Atropos integration (`environments/`) ships via the `atroposlib` and `tinker` dependencies pulled in by `.[all,dev]` — no submodule setup required. --- ## Community - 💬 [Discord](https://discord.gg/NousResearch) - 📚 [Skills Hub](https://agentskills.io) - 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues) - 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account. --- ## Clipboard Troubleshooting Hermes TUI (standalone) and dashboard both support copying via `Ctrl+C` / `Cmd+C`. This requires either: - A terminal with **OSC 52** support enabled, **or** - Native clipboard utilities (`pbcopy`, `wl-copy`, `xclip`, `xsel`, `clip.exe`) available in PATH **and** a running display server (X11 or Wayland). If the UI says "copied" but the text is not in your system clipboard, follow these steps. ### Standalone TUI (`hermes --tui`) #### Verify OSC 52 support Run this in the same terminal you use for Hermes: ```bash printf '\e]52;c;%s\a' "$(echo -n 'test-osc52' | base64)" && echo ``` Then paste (Cmd+V / Ctrl+Shift+V). If you see `test-osc52`, OSC 52 works. If it fails, enable OSC 52 in your terminal: | Terminal | Setting | |--------------|-------------------------------------------------------------------------| | iTerm2 | Preferences → General → Selection → check "Copy to pasteboard" | | Kitty | `allow_remote_control yes` (default: on) | | WezTerm | `enable_osc52_copy = true` | | VS Code | Usually works; if blocked, check DevTools console for permission error | | GNOME | Enabled by default | #### tmux users tmux absorbs OSC 52 unless explicitly configured. Add to `~/.tmux.conf`: ```tmux set -g set-clipboard on set -g allow-passthrough on ``` Then reload: `tmux source-file ~/.tmux.conf`. #### Docker/headless environments Inside a Docker container, `$DISPLAY` and `$WAYLAND_DISPLAY` are typically unset, so native clipboard tools fail immediately. OSC 52 is the only path — it must be supported by your local terminal emulator (the one connected to the container's PTY). If your terminal doesn't support OSC 52, consider: - Using `ssh -X` / `ssh -Y` to forward X11 and run `xclip` on the host via SSH - Running Hermes on the host directly, not inside a container - Writing copied text to a file: `/copy` saves to `~/.hermes/clipboard.txt` (fallback) #### Force OSC 52 emission If your terminal supports OSC 52 but Hermes isn't emitting it (e.g., inside SSH where native tools are skipped), set: ```bash export HERMES_TUI_CLIPBOARD_OSC52=1 hermes --tui ``` #### Debug mode To see exactly which clipboard path Hermes takes: ```bash export HERMES_TUI_DEBUG_CLIPBOARD=1 hermes --tui ``` Then attempt a copy and watch stderr for messages like: ``` [clipboard] [native] Linux: no DISPLAY or WAYLAND_DISPLAY — native clipboard unavailable [clipboard] [native] Linux: clipboard probe complete → xclip [clipboard] [osc52] no sequence emitted — native clipboard or tmux buffer path in use ``` ### Dashboard (`hermes dashboard` → /chat) The dashboard uses the browser's Clipboard API. There are two copy paths: 1. **Ctrl/Cmd+Shift+C** — direct copy from xterm's selection (most reliable) 2. **Ink's Ctrl+C** — emits OSC 52 → xterm OSC 52 handler → Clipboard API; this is more fragile because the Clipboard API requires a **user gesture**. In some browsers the OSC 52 response is processed outside the original key event's activation window, causing a silent failure. If copy doesn't work in the dashboard: - Use `Ctrl+Shift+C` (Linux/Windows) or `Cmd+Shift+C` (macOS) instead - Check the browser console (F12) for warnings like `[dashboard clipboard] OSC 52 write failed` - Ensure the page has clipboard permissions (browser may ask on first use) Clicking the "copy last response" button also sends `/copy` over the WebSocket, which suffers from the same OSC 52 timing issue. ### When all else fails: file-based fallback You can save copied text to a file manually: ```bash hermes --tui # inside TUI, use /copy which includes a file fallback in future versions ``` Or implement a custom skill that writes the last assistant message to disk. --- ## License MIT — see [LICENSE](LICENSE). Built by [Nous Research](https://nousresearch.com).