How sayminomo/hermes-agent works
1. This is a multi-surface AI agent platform, not a single app. The repo centers on a shared Python agent core, with three main user-facing surfaces: the terminal CLI/TUI, the messaging gateway, and a browser/web dashboard. Supporting them are provider integrations, tools, memory, skills, plugins, and a docs site.
2. The core orchestration lives in agent/ and run_agent.py. This is where conversation turns are assembled, context is compressed, tool calls are executed, retries/fallbacks happen, and outputs are streamed back. The core also owns policy/guardrail behavior such as file safety, redaction, rate limiting, and result classification.
3. Model access is abstracted behind provider/transports boundaries. agent/transports/ and providers/ separate “what the agent wants” from “which model/vendor is used.” The repo supports many backends: Anthropic, Bedrock, Gemini, OpenAI-style chat/completions, Codex-specific flows, and custom provider plugins. Model selection, fallback, and auth live above the transport layer.
4. Tools are first-class and heavily modularized. tools/ contains the actual capabilities the agent can invoke: shell/terminal, file operations, browser, code execution, MCP, transcription/TTS, vision, web search, message sending, memory lookup, and more. Tool execution is mediated by shared guards, output limits, approval flows, and environment backends.
5. There is a distinct execution-environment layer. tools/environments/ and related modules isolate where tool actions run: local, Docker, SSH, Daytona, Modal, Singularity, and Vercel Sandbox. This boundary matters because many tools are not executed in-process; they are routed into a chosen runtime that provides filesystem, process, and network isolation.
6. Stateful conversation features are a separate subsystem. Session storage, trajectory capture, context references, memory management, and compression live across agent/session-related modules, hermes_state.py, trajectory_compressor.py, and persistence helpers. The agent is designed to retain cross-session knowledge and to compress older context rather than keep all history inline.
7. Skills are the agent’s procedural memory and capability catalog. The skills/, optional-skills/, and agent/skill_* modules define reusable task recipes, command syntax, and capability discovery. Skills are surfaced in both the CLI and web UI, can be installed or synchronized, and are part of the “self-improving” loop described in the README.
8. The CLI/TUI surface is a substantial application of its own. hermes_cli/ contains command parsing, setup/auth flows, model switching, profile management, cron, plugins, web server hooks, and the terminal UX. The separate ui-tui/ package is the TypeScript/Ink-based interface that renders the interactive terminal experience, manages input/history/scrolling, and talks to the backend through a local gateway/RPC layer.
9. The messaging gateway is the multi-platform ingress/egress layer. gateway/ normalizes events from Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, Feishu, WeCom, QQ, Teams, and webhook-style integrations. It handles channel/session mapping, delivery, mirror/restart logic, deduplication, pairing/auth, and platform-specific adapters so that all platforms converge on the same agent conversation model.
10. Gateway and CLI ultimately converge on the same session and tool model. Whether a message comes from the TUI or from Telegram/Discord, it is routed into a shared session context, then into the core agent loop, then back out through the appropriate renderer or platform adapter. That makes “conversation” the central domain object, with the channel acting as a transport boundary.
11. acp_adapter/ exposes Hermes as an external protocol/server. It provides a dedicated adapter/server/session/auth layer for ACP-style integration, with event translation and tool exposure. This is an integration boundary for external clients that want to drive the agent without using the CLI or messaging gateway directly.
12. Plugins extend the platform without changing the core. plugins/ contains packaged extensions for model providers, memory backends, image/video generation, web search, observability, meeting workflows, and dashboard plugins. Each plugin has its own manifest and often its own runtime or UI assets, which keeps third-party capabilities isolated from the main agent implementation.
13. There is a browser/web dashboard, plus a separate documentation website. web/ is the product dashboard UI that presents chats, sessions, configs, models, plugins, skills, logs, and analytics. website/ is the Docusaurus docs site and static reference content; it documents the architecture and user workflows but is not part of the runtime agent path.
14. Automation and background execution are built in. cron/, batch_runner.py, mini_swe_runner.py, and the scheduling-related code let Hermes run unattended jobs, generate reports, and deliver results back to messaging platforms. This is important architecturally because Hermes is designed for both interactive and autonomous operation.
15. Tests mirror the architecture and are a strong map of boundaries. The repo has separate test suites for agent core, CLI, gateway, tools, plugins, ACP, cron, and the TUI/web layers. That separation reflects the intended runtime boundaries and is a good clue for diagramming: shared core in the middle, multiple thin surfaces around it, and external services at the edges.
Main entry points: agent agent · tools tools · run_agent.py run_agent.py · gateway gateway
Components 20
Agent Core
Shared Python orchestration, state, policy, and model access.
- run_agent.py · Main agent execution path for turns, streaming, retries, and tool execution.
run_agent.py - agent · Conversation assembly, prompt building, context compression, guardrails, and provider adapters.
agent - transports · Vendor-facing transport abstractions and protocol-specific model flows.
agent/transports - providers · Shared provider interface and package-level provider plumbing.
providers - hermes_state.py · Persistent session and resume state shared across surfaces.
hermes_state.py - trajectory_compressor.py · Compresses older conversation history and maintains compact trajectory state.
trajectory_compressor.py
User Surfaces
Interactive entry points that feed the same session and agent loop.
- hermes_cli · Terminal command layer for auth, setup, model switching, profiles, cron, and utilities.
hermes_cli - ui-tui · Ink-based terminal UI that renders chat, history, inputs, and gateway-backed state.
ui-tui - tui_gateway · Local transport between the TUI process and the backend agent/session model.
tui_gateway - web · Browser dashboard for chats, sessions, models, plugins, skills, configs, and logs.
web
External Integrations
Protocols, messaging adapters, and runtime boundaries for outside systems.
- gateway · Multi-platform ingress and egress for chat services, sessions, delivery, and platform adapters.
gateway - acp_adapter · ACP-style external protocol server and session bridge.
acp_adapter - cron · Scheduled and unattended job execution for autonomous operation.
cron - batch_runner.py · Batch execution entrypoint for autonomous or offline runs.
batch_runner.py
Extensibility
Plugins, skills, and specialized tool families that extend the platform.
- tools · First-class tool implementations with guards, limits, and execution mediation.
tools - environments · Isolation layer for local, containerized, remote, and sandboxed tool execution.
tools/environments - skills · Procedural task recipes and capability definitions surfaced to the agent.
skills - optional-skills · Additional skill packs and optional capability bundles.
optional-skills - plugins · Packaged extensions for providers, memory, search, media, dashboards, and workflows.
plugins
Docs & Site
Documentation and website assets explaining the system.
- website · Docusaurus documentation site and reference content.
website
Connections 23
- run_agent.py → agent: orchestrates · Delegates each turn to the shared agent loop and policy stack.
- agent → transports: uses · Sends requests through transport abstractions to model backends.
- agent → providers: selects providers · Resolves provider implementations and fallback behavior.
- agent → tools: invokes · Executes tool calls and classifies results through shared guards.
- agent → trajectory_compressor.py: compresses context · Reduces conversation history and preserves salient trajectory state.
- agent → hermes_state.py: persists session · Reads and updates resumable conversation/session state.
- tools → environments: runs in · Routes tool actions into the selected execution environment.
- tools → skills: exposes capabilities · Uses skills as procedural memory and tool-facing recipes.
- skills → optional-skills: extends with · Loads optional skill packs alongside bundled skills.
- plugins → agent: extends · Adds provider, memory, search, media, and workflow capabilities without changing core.
- hermes_cli → run_agent.py: launches · Starts interactive or one-shot agent runs from the terminal.
- hermes_cli → tui_gateway: bridges to · Connects the Python CLI to the TUI transport layer.
- ui-tui → tui_gateway: talks to · Uses the local gateway/RPC channel for session and event sync.
- tui_gateway → agent: feeds · Turns local terminal events into shared agent/session operations.
- gateway → agent: feeds · Normalizes platform events into the same conversation model and hands off to core.
- gateway → hermes_state.py: maps sessions · Maintains channel/session binding and conversation continuity.
- acp_adapter → agent: adapts to · Translates ACP client events into agent/session actions.
- cron → run_agent.py: schedules · Triggers unattended or recurring agent jobs.
- batch_runner.py → run_agent.py: wraps · Provides a batch-oriented entry path into the agent loop.
- web → gateway: consumes API · Uses backend session and chat APIs rather than owning the agent core.
- web → hermes_state.py: displays · Shows session, model, plugin, and log state to users.
- website → skills: documents · Publishes the skills catalog and user guidance.
- website → tools: documents · Describes tool usage and toolsets for users and contributors.