24fa055763
* docs: fix ascii-guard border alignment errors Three docs pages had ASCII diagram boxes with off-by-one column alignment issues that failed docs-site-checks CI: - architecture.md: outer box is 71 cols but inner-box content lines and border corners were offset by 1 col, making content-line right border at col 70/72 while top/bottom border was at col 71. Inner boxes also had border corners at cols 19/36/53 but content pipes at cols 20/37/54. Rewrote the diagram with consistent 71-col width throughout, aligned inner boxes at cols 4-19, 22-37, 40-55 with 2-space gaps and 15-space trailing padding. - gateway-internals.md: same class of issue — outer box at 51 cols, inner content lines varied 52-54 cols. Rewrote with consistent 51-col width, inner boxes at cols 4-15, 18-29, 32-43. Also restructured the bottom-half message flow so it's bare text (not half-open box cells) matching the intent of the original. - agent-loop.md line 112-114: box 2 (API thread) content lines had one extra space pushing the right border to col 46 while the top and bottom borders of that box sat at col 45. Trimmed one trailing space from each of the three content lines. All 123 docs files now pass `npm run lint:diagrams`: ✓ Errors: 0 (warnings: 6, non-fatal) Pre-existing failures on main — unrelated to any open PR. * test(setup): accept description kwarg in prompt_choice mock lambdas setup.py's `_curses_prompt_choice` gained an optional `description` parameter (used for rendering context hints alongside the prompt). `prompt_choice` forwards it via keyword arg. The two existing tests mocked `_curses_prompt_choice` with lambdas that didn't accept the new kwarg, so the forwarded call raised TypeError. Fix: add `description=None` to both mock lambda signatures so they absorb the new kwarg without changing behavior. * test(matrix): update stale audio-caching assertion test_regular_audio_has_http_url asserted that non-voice audio messages keep their HTTP URL and are NOT downloaded/cached. That was true when the caching code only triggered on `is_voice_message`. Since bec02f37 (encrypted-media caching refactor), matrix.py caches all media locally — photos, audio, video, documents — so downstream tools can read them as real files via media_urls. This applies to regular audio too. Renamed the test to `test_regular_audio_is_cached_locally`, flipped the assertions accordingly, and documented the intentional behavior change in the docstring. Other tests in the file (voice-specific caching, message-type detection, reply-to threading) continue to pass. * test(413): allow multi-pass preflight compression run_agent.py's preflight compression runs up to 3 passes in a loop for very large sessions (each pass summarizes the middle N turns, then re-checks tokens). The loop breaks when a pass returns a message list no shorter than its input (can't compress further). test_preflight_compresses_oversized_history used a static mock return value that returned the same 2 messages regardless of input, so the loop ran pass 1 (41 -> 2) and pass 2 (2 -> 2 -> break), making call_count == 2. The assert_called_once() assertion was strictly wrong under the multi-pass design. The invariant the test actually cares about is: preflight ran, and its first invocation received the full oversized history. Replaced the count assertion with those two invariants. * docs: drop '...' from gateway diagram, merge side-by-side boxes ascii-guard 2.3.0 flagged two remaining issues after the initial fix pass: 1. gateway-internals.md L33: the '...' suffix after inner box 3's right border got parsed as 'extra characters after inner-box right border'. Dropped the '...' — the surrounding prose already conveys 'and more platforms' without needing the visual hint. 2. agent-loop.md: ascii-guard can't cleanly parse two side-by-side boxes of different heights (main thread 7 rows, API thread 5 rows). Even equalizing heights didn't help — the linter treats the left box's right border as the end of the diagram. Merged into a single 54-char-wide outer box with both threads labeled as regions inside, keeping the ▶ arrow to preserve the main→API flow direction.
Hermes Agent ☤
The self-improving AI agent built by Nous Research. 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, OpenRouter (200+ models), Xiaomi MiMo, z.ai/GLM, Kimi/Moonshot, MiniMax, Hugging Face, 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
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. 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 and run the command above.
After installation:
source ~/.bashrc # reload shell (or: source ~/.zshrc)
hermes # start chatting!
Getting Started
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
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 /<skill-name> |
/skills or /<skill-name> |
| 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 and the Messaging Gateway guide.
Documentation
All documentation lives at hermes-agent.nousresearch.com/docs:
| Section | What's Covered |
|---|---|
| Quickstart | Install → setup → first conversation in 2 minutes |
| CLI Usage | Commands, keybindings, personalities, sessions |
| Configuration | Config file, providers, models, all options |
| Messaging Gateway | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
| Security | Command approval, DM pairing, container isolation |
| Tools & Toolsets | 40+ tools, toolset system, terminal backends |
| Skills System | Procedural memory, Skills Hub, creating skills |
| Memory | Persistent memory, user profiles, best practices |
| MCP Integration | Connect any MCP server for extended capabilities |
| Cron Scheduling | Scheduled tasks with platform delivery |
| Context Files | Project context that shapes every conversation |
| Architecture | Project structure, agent loop, key classes |
| Contributing | Development setup, PR process, code style |
| CLI Reference | All commands and flags |
| 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:
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 for development setup, code style, and PR process.
Quick start for contributors:
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
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]"
python -m pytest tests/ -q
RL Training (optional): To work on the RL/Tinker-Atropos integration:
git submodule update --init tinker-atropos uv pip install -e "./tinker-atropos"
Community
- 💬 Discord
- 📚 Skills Hub
- 🐛 Issues
- 💡 Discussions
- 🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
License
MIT — see LICENSE.
Built by Nous Research.