hermes-agent

name hermes-agent description Expert in building self-improving AI agents with tool use, multi-platform messaging, and a closed learning loop. Proficient in LLM orchestration, tool integration, session management, and agent autonomy. Hermes Agent - Complete Project Guide (A-Z) Purpose of this document: A single, comprehensive reference that explains everything about the Hermes Agent project — its architecture, source code, features, release history, and design patterns — so that any AI or developer can fully understand the system. Table of Contents Project Overview Key Features Summary Installation & Getting Started Project Structure Core Architecture 5.1 AIAgent Class (run_agent.py) 5.2 Tool Orchestration (model_tools.py) 5.3 Toolset System (toolsets.py) 5.4 Tool Registry (tools/registry.py) 5.5 Session Database (hermes_state.py) 5.6 Constants & Home Directory (hermes_constants.py) CLI System 6.1 Interactive CLI (cli.py) 6.2 CLI Entry Point (hermes_cli/main.py) 6.3 Configuration System (hermes_cli/config.py) 6.4 Slash Command Registry (hermes_cli/commands.py) 6.5 Setup Wizard (hermes_cli/setup.py) 6.6 Model Catalog (hermes_cli/models.py) 6.7 Skin/Theme Engine (hermes_cli/skin_engine.py) Tool System 7.1 Terminal Tool (tools/terminal_tool.py) 7.2 File Tools (tools/file_tools.py) 7.3 Web Tools (tools/web_tools.py) 7.4 Browser Tool (tools/browser_tool.py) 7.5 Delegate Tool (tools/delegate_tool.py) 7.6 MCP Tool (tools/mcp_tool.py) 7.7 Approval System (tools/approval.py) 7.8 Terminal Backends (tools/environments/) Agent Internals 8.1 Prompt Builder (agent/prompt_builder.py) 8.2 Context Compressor (agent/context_compressor.py) 8.3 Prompt Caching (agent/prompt_caching.py) 8.4 Auxiliary Client (agent/auxiliary_client.py) 8.5 Display & Spinner (agent/display.py) 8.6 Skill Commands (agent/skill_commands.py) Messaging Gateway 9.1 GatewayRunner (gateway/run.py) 9.2 Session Store (gateway/session.py) 9.3 Platform Adapters (gateway/platforms/) Cron Scheduling Skills System Plugin System Memory System ACP Server (IDE Integration) API Server MCP Server Mode RL Training Environments Profiles (Multi-Instance) Security Model Provider & Model System Streaming & Reasoning Release History File Dependency Chain Key Design Patterns Configuration Reference Known Pitfalls 1. Project Overview Hermes Agent is a self-improving AI agent built by Nous Research . It is an open-source (MIT licensed), Python-based project that provides: A full interactive terminal UI (CLI) for conversing with LLMs A messaging gateway supporting 16+ platforms (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, etc.) A closed learning loop — the agent creates skills from experience, improves them during use, nudges itself to persist knowledge, searches past conversations, and builds a deepening model of who you are 40+ built-in tools — terminal execution, file manipulation, web search, browser automation, code execution, image generation, TTS/STT, and more Any LLM provider — OpenRouter (200+ models), Nous Portal (400+ models), OpenAI, Anthropic, Hugging Face, GitHub Copilot, z.ai/GLM, Kimi/Moonshot, MiniMax, Alibaba/DashScope, custom endpoints Six terminal backends — local, Docker, SSH, Modal (serverless), Daytona (serverless), Singularity (HPC) Scheduled automations via built-in cron scheduler IDE integration via ACP (Agent Communication Protocol) for VS Code, Zed, JetBrains MCP integration — both client (connect to any MCP server) and server (expose Hermes to MCP clients) RL training via Atropos environments for training the next generation of tool-calling models Tech Stack: Python 3.11+ (core agent, tools, gateway, cron) Node.js (browser automation via agent-browser) SQLite with WAL mode and FTS5 (session storage, full-text search) OpenAI-compatible API (primary inference interface) Anthropic SDK (native Anthropic support) Rich + prompt_toolkit (CLI rendering) Repository: github.com/NousResearch/hermes-agent Version: 0.7.0 (as of April 2026) License: MIT 2. Key Features Summary Feature Description Terminal UI Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, streaming tool output Multi-Platform Messaging Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, Home Assistant, DingTalk, Feishu/Lark, WeCom, Mattermost, SMS, Webhook — all from a single gateway process Learning Loop Agent-curated memory with periodic nudges, autonomous skill creation, skills self-improve during use, FTS5 session search with LLM summarization, Honcho dialectic user modeling Scheduled Tasks Built-in cron scheduler with delivery to any platform (daily reports, nightly backups, weekly audits) Subagent Delegation Spawn isolated subagents for parallel workstreams with restricted toolsets Execute Code Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns Terminal Backends Local, Docker, SSH, Modal, Daytona, Singularity — run on a $5 VPS or a GPU cluster Skills 70+ bundled skills across 28 categories, Skills Hub for community discovery, agentskills.io compatibility Plugins Drop-in Python plugins with lifecycle hooks (pre_llm_call, post_llm_call, on_session_start, on_session_end) MCP Client (connect to MCP servers for extended tools) and Server (expose conversations to MCP clients) IDE Integration VS Code, Zed, JetBrains via ACP server with session management and tool streaming API Server OpenAI-compatible /v1/chat/completions endpoint for headless integrations Profiles Multi-instance support — each profile gets isolated config, memory, sessions, skills, gateway Security Command approval system, secret redaction, SSRF protection, PII redaction, injection detection, credential directory protection RL Training Atropos environments for batch trajectory generation and agent policy optimization 3. Installation & Getting Started # One-line install (Linux, macOS, WSL2) curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # After install source ~/.bashrc # or: source ~/.zshrc hermes # start chatting # Key commands hermes model # Choose LLM provider and model hermes tools # Configure which tools are enabled hermes config set # Set individual config values hermes gateway # Start the messaging gateway hermes setup # Run the full setup wizard hermes update # Update to latest version hermes doctor # Diagnose any issues For development: 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 # ~3000 tests 4. Project Structure hermes-agent/ ├── run_agent.py # AIAgent class — core conversation loop ├── model_tools.py # Tool orchestration, _discover_tools(), handle_function_call() ├── toolsets.py # Toolset definitions, _HERMES_CORE_TOOLS list ├── toolset_distributions.py # Toolset sampling distributions for RL ├── cli.py # HermesCLI class — interactive CLI orchestrator ├── hermes_state.py # SessionDB — SQLite session store (FTS5 search) ├── hermes_constants.py # Shared constants, get_hermes_home() ├── hermes_time.py # Timezone handling ├── utils.py # Shared utility functions ├── batch_runner.py # Parallel batch processing ├── trajectory_compressor.py # Trajectory compression for RL training ├── mcp_serve.py # MCP server mode entry point ├── mini_swe_runner.py # Minimal SWE benchmark runner ├── rl_cli.py # RL CLI commands │ ├── agent/ # Agent internals │ ├── prompt_builder.py # System prompt assembly │ ├── context_compressor.py # Auto context compression │ ├── prompt_caching.py # Anthropic prompt caching │ ├── auxiliary_client.py # Auxiliary LLM client (vision, summarization) │ ├── model_metadata.py # Model context lengths, token estimation │ ├── models_dev.py # models.dev registry integration │ ├── display.py # KawaiiSpinner, tool preview formatting │ ├── skill_commands.py # Skill slash commands (shared CLI/gateway) │ └── trajectory.py # Trajectory saving helpers │ ├── hermes_cli/ # CLI subcommands and setup │ ├── main.py # Entry point — all `hermes` subcommands │ ├── config.py # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration │ ├── commands.py # Slash command definitions + SlashCommandCompleter │ ├── callbacks.py # Terminal callbacks (clarify, sudo, approval) │ ├── setup.py # Interactive setup wizard │ ├── skin_engine.py # Skin/theme engine │ ├── skills_config.py # `hermes skills` — skill management │ ├── tools_config.py # `hermes tools` — tool management │ ├── skills_hub.py # Skills Hub integration │ ├── models.py # Model catalog, provider model lists │ ├── model_switch.py # Shared /model switch pipeline │ └── auth.py # Provider credential resolution │ ├── tools/ # Tool implementations (one file per tool) │ ├── registry.py # Central tool registry │ ├── approval.py # Dangerous command detection │ ├── terminal_tool.py # Terminal/shell execution │ ├── process_registry.py # Background process management │ ├── file_tools.py # File read/write/search/patch │ ├── web_tools.py # Web search/extract │ ├── browser_tool.py # Browser automation │ ├── code_execution_tool.py # execute_code sandbox │ ├── delegate_tool.py # Subagent delegation │ ├── mcp_tool.py # MCP client integration │ ├── skills_tool.py # Skill management tool │ ├── todo_tool.py # Todo/task tracking tool │ ├── memory_tool.py # Memory read/write tool │ ├── tts_tool.py # Text-to-speech │ ├── vision_tool.py # Image analysis │ ├── image_gen_tool.py # Image generation │ └── environments/ # Terminal backends │ ├── base.py # BaseEnvironment ABC │ ├── local.py # Local execution │ ├── docker.py # Docker containers │ ├── ssh.py # SSH remote execution │ ├── modal.py # Modal serverless │ ├── managed_modal.py # Nous-hosted Modal │ ├── daytona.py # Daytona serverless │ ├── singularity.py # Singularity HPC containers │ └── persistent_shell.py # Persistent shell mixin │ ├── gateway/ # Messaging platform gateway │ ├── run.py # GatewayRunner — main message loop │ ├── session.py # SessionStore — conversation persistence │ ├── status.py # Gateway status, token locks │ └── platforms/ # 16 platform adapters │ ├── base.py # BasePlatformAdapter ABC │ ├── telegram.py # Telegram (polling + webhook) │ ├── discord.py # Discord │ ├── slack.py # Slack │ ├── whatsapp.py # WhatsApp │ ├── matrix.py # Matrix (E2EE) │ ├── signal.py # Signal │ ├── email.py # Email (IMAP/SMTP) │ ├── homeassistant.py # Home Assistant │ ├── sms.py # SMS (Twilio) │ ├── mattermost.py # Mattermost │ ├── dingtalk.py # DingTalk │ ├── feishu.py # Feishu/Lark │ ├── wecom.py # WeCom (Enterprise WeChat) │ ├── webhook.py # Generic webhook │ └── api_server.py # OpenAI-compatible API server │ ├── acp_adapter/ # ACP server (IDE integration) │ ├── server.py # HermesACPAgent class │ ├── session.py # SessionManager │ ├── events.py # Streaming callbacks │ ├── permissions.py # Approval callbacks │ └── entry.py # Entry point │ ├── cron/ # Scheduler │ ├── scheduler.py # tick() — job execution engine