# sayminomo/hermes-agent architecture

> Architecture diagram of the GitHub repository sayminomo/hermes-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sayminomo/hermes-agent
- Repository: https://github.com/sayminomo/hermes-agent

## Overview

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`](https://github.com/sayminomo/hermes-agent/tree/main/agent) (agent), [`tools`](https://github.com/sayminomo/hermes-agent/tree/main/tools) (tools), [`run_agent.py`](https://github.com/sayminomo/hermes-agent/blob/main/run_agent.py) (run_agent.py), [`gateway`](https://github.com/sayminomo/hermes-agent/tree/main/gateway) (gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Agent Core"]
  node_run_agent["run_agent.py<br/>agent loop entry<br/>[run_agent.py]"]
  node_agent_core["agent<br/>core orchestration"]
  node_agent_transports["transports<br/>model transport layer"]
  node_providers_pkg["providers<br/>provider boundary"]
  node_state["hermes_state.py<br/>session state<br/>[hermes_state.py]"]
  node_compressor["trajectory_compressor.py<br/>context compression"]
end

subgraph group_surfaces["User Surfaces"]
  node_hermes_cli["hermes_cli<br/>python CLI"]
  node_ui_tui["ui-tui<br/>typescript TUI"]
  node_tui_gateway["tui_gateway<br/>local rpc bridge"]
  node_web["web<br/>dashboard app"]
end

subgraph group_integrations["External Integrations"]
  node_gateway["gateway"]
  node_acp_adapter["acp_adapter<br/>protocol adapter"]
  node_cron["cron<br/>automation scheduler"]
  node_run_batch["batch_runner.py<br/>batch entrypoint<br/>[batch_runner.py]"]
end

subgraph group_extensibility["Extensibility"]
  node_tools["tools<br/>tool runtime"]
  node_tool_envs["environments"]
  node_skills["skills"]
  node_optional_skills["optional-skills<br/>extra skills"]
  node_plugins["plugins<br/>plugin system"]
end

subgraph group_docs["Docs & Site"]
  node_website["website<br/>docs site"]
end

node_run_agent -->|"orchestrates"| node_agent_core
node_agent_core -->|"uses"| node_agent_transports
node_agent_core -->|"selects providers"| node_providers_pkg
node_agent_core -->|"invokes"| node_tools
node_agent_core -->|"compresses context"| node_compressor
node_agent_core -->|"persists session"| node_state
node_tools -->|"runs in"| node_tool_envs
node_tools -->|"exposes capabilities"| node_skills
node_skills -->|"extends with"| node_optional_skills
node_plugins -->|"extends"| node_agent_core
node_hermes_cli -->|"launches"| node_run_agent
node_hermes_cli -->|"bridges to"| node_tui_gateway
node_ui_tui -->|"talks to"| node_tui_gateway
node_tui_gateway -->|"feeds"| node_agent_core
node_gateway -->|"feeds"| node_agent_core
node_gateway -->|"maps sessions"| node_state
node_acp_adapter -->|"adapts to"| node_agent_core
node_cron -->|"schedules"| node_run_agent
node_run_batch -->|"wraps"| node_run_agent
node_web -->|"consumes API"| node_gateway
node_web -->|"displays"| node_state
node_website -->|"documents"| node_skills
node_website -->|"documents"| node_tools

click node_run_agent "https://github.com/sayminomo/hermes-agent/blob/main/run_agent.py"
click node_agent_core "https://github.com/sayminomo/hermes-agent/tree/main/agent"
click node_agent_transports "https://github.com/sayminomo/hermes-agent/tree/main/agent/transports"
click node_providers_pkg "https://github.com/sayminomo/hermes-agent/tree/main/providers"
click node_state "https://github.com/sayminomo/hermes-agent/blob/main/hermes_state.py"
click node_compressor "https://github.com/sayminomo/hermes-agent/blob/main/trajectory_compressor.py"
click node_tools "https://github.com/sayminomo/hermes-agent/tree/main/tools"
click node_tool_envs "https://github.com/sayminomo/hermes-agent/tree/main/tools/environments"
click node_skills "https://github.com/sayminomo/hermes-agent/tree/main/skills"
click node_optional_skills "https://github.com/sayminomo/hermes-agent/tree/main/optional-skills"
click node_plugins "https://github.com/sayminomo/hermes-agent/tree/main/plugins"
click node_hermes_cli "https://github.com/sayminomo/hermes-agent/tree/main/hermes_cli"
click node_ui_tui "https://github.com/sayminomo/hermes-agent/tree/main/ui-tui"
click node_gateway "https://github.com/sayminomo/hermes-agent/tree/main/gateway"
click node_acp_adapter "https://github.com/sayminomo/hermes-agent/tree/main/acp_adapter"
click node_tui_gateway "https://github.com/sayminomo/hermes-agent/tree/main/tui_gateway"
click node_web "https://github.com/sayminomo/hermes-agent/tree/main/web"
click node_website "https://github.com/sayminomo/hermes-agent/tree/main/website"
click node_cron "https://github.com/sayminomo/hermes-agent/tree/main/cron"
click node_run_batch "https://github.com/sayminomo/hermes-agent/blob/main/batch_runner.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_run_agent,node_agent_core,node_agent_transports,node_providers_pkg,node_state,node_compressor toneBlue
class node_hermes_cli,node_ui_tui,node_tui_gateway,node_web toneAmber
class node_gateway,node_acp_adapter,node_cron,node_run_batch toneMint
class node_tools,node_tool_envs,node_skills,node_optional_skills,node_plugins toneRose
class node_website toneIndigo
```

## Components

### Agent Core

Shared Python orchestration, state, policy, and model access.

- [run_agent.py](https://github.com/sayminomo/hermes-agent/blob/main/run_agent.py): agent loop entry · Main agent execution path for turns, streaming, retries, and tool execution. · `run_agent.py`
- [agent](https://github.com/sayminomo/hermes-agent/tree/main/agent): core orchestration · Conversation assembly, prompt building, context compression, guardrails, and provider adapters. · `agent`
- [transports](https://github.com/sayminomo/hermes-agent/tree/main/agent/transports): model transport layer · Vendor-facing transport abstractions and protocol-specific model flows. · `agent/transports`
- [providers](https://github.com/sayminomo/hermes-agent/tree/main/providers): provider boundary · Shared provider interface and package-level provider plumbing. · `providers`
- [hermes_state.py](https://github.com/sayminomo/hermes-agent/blob/main/hermes_state.py): session state · Persistent session and resume state shared across surfaces. · `hermes_state.py`
- [trajectory_compressor.py](https://github.com/sayminomo/hermes-agent/blob/main/trajectory_compressor.py): context compression · 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](https://github.com/sayminomo/hermes-agent/tree/main/hermes_cli): python CLI · Terminal command layer for auth, setup, model switching, profiles, cron, and utilities. · `hermes_cli`
- [ui-tui](https://github.com/sayminomo/hermes-agent/tree/main/ui-tui): typescript TUI · Ink-based terminal UI that renders chat, history, inputs, and gateway-backed state. · `ui-tui`
- [tui_gateway](https://github.com/sayminomo/hermes-agent/tree/main/tui_gateway): local rpc bridge · Local transport between the TUI process and the backend agent/session model. · `tui_gateway`
- [web](https://github.com/sayminomo/hermes-agent/tree/main/web): dashboard app · Browser dashboard for chats, sessions, models, plugins, skills, configs, and logs. · `web`

### External Integrations

Protocols, messaging adapters, and runtime boundaries for outside systems.

- [gateway](https://github.com/sayminomo/hermes-agent/tree/main/gateway): messaging gateway · Multi-platform ingress and egress for chat services, sessions, delivery, and platform adapters. · `gateway`
- [acp_adapter](https://github.com/sayminomo/hermes-agent/tree/main/acp_adapter): protocol adapter · ACP-style external protocol server and session bridge. · `acp_adapter`
- [cron](https://github.com/sayminomo/hermes-agent/tree/main/cron): automation scheduler · Scheduled and unattended job execution for autonomous operation. · `cron`
- [batch_runner.py](https://github.com/sayminomo/hermes-agent/blob/main/batch_runner.py): batch entrypoint · Batch execution entrypoint for autonomous or offline runs. · `batch_runner.py`

### Extensibility

Plugins, skills, and specialized tool families that extend the platform.

- [tools](https://github.com/sayminomo/hermes-agent/tree/main/tools): tool runtime · First-class tool implementations with guards, limits, and execution mediation. · `tools`
- [environments](https://github.com/sayminomo/hermes-agent/tree/main/tools/environments): execution environments · Isolation layer for local, containerized, remote, and sandboxed tool execution. · `tools/environments`
- [skills](https://github.com/sayminomo/hermes-agent/tree/main/skills): bundled skills · Procedural task recipes and capability definitions surfaced to the agent. · `skills`
- [optional-skills](https://github.com/sayminomo/hermes-agent/tree/main/optional-skills): extra skills · Additional skill packs and optional capability bundles. · `optional-skills`
- [plugins](https://github.com/sayminomo/hermes-agent/tree/main/plugins): plugin system · Packaged extensions for providers, memory, search, media, dashboards, and workflows. · `plugins`

### Docs & Site

Documentation and website assets explaining the system.

- [website](https://github.com/sayminomo/hermes-agent/tree/main/website): docs site · Docusaurus documentation site and reference content. · `website`

## Connections

- 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.
