# skygod07/hermes-agent architecture

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

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

## Overview

Hermes is a self-improving AI agent exposed through CLI/TUI, messaging platforms, and a desktop app. The main loop takes a user prompt, runs model-driven turns and tools, then returns a response; memory and skill creation extend learning across sessions. The README also documents scheduling, subagents, multiple execution backends, and trajectory generation. The graph combines those documented capabilities with relationships visible in the supplied source index; several subsystems were not sampled, so their internal links are omitted.

Main entry points: [`agent/conversation_loop.py`](https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation Loop), [`gateway/platforms/base.py`](https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/base.py) (Messaging Gateway), [`run_agent.py`](https://github.com/skygod07/hermes-agent/blob/main/run_agent.py) (Agent Entry), [`cli.py`](https://github.com/skygod07/hermes-agent/blob/main/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_desktop["Desktop App"]
end

subgraph group_runtime["Agent Runtime"]
  node_entry["Agent Entry<br/>[run_agent.py]"]
  node_turnloop["Conversation Loop"]
end

subgraph group_learning["Tools and Learning"]
  node_tooling["Tool Execution<br/>[terminal_tool.py]"]
  node_memory["Memory Manager<br/>[memory_manager.py]"]
  node_skills["Skill Learning<br/>[skill_commands.py]"]
end

subgraph group_integrations["Channels and Providers"]
  node_gateway["Messaging Gateway<br/>[base.py]"]
  node_webhook["Webhook Adapter<br/>[webhook.py]"]
  node_signal["Signal Adapter<br/>[signal.py]"]
  node_providers["Model Providers<br/>[model_metadata.py]"]
end

subgraph group_execution["Execution and Research"]
  node_scheduler["Scheduled Jobs<br/>[config.py]"]
  node_subagents["Subagents"]
  node_backends["Execution Backends"]
  node_trajectory["Trajectory Research<br/>[trajectory.py]"]
  node_lsp["Language Services<br/>[manager.py]"]
end

node_user(("User"))

node_user -->|"prompts"| node_cli
node_user -->|"prompts"| node_tui
node_user -->|"uses"| node_desktop
node_user -->|"messages"| node_gateway
node_cli -->|"starts"| node_entry
node_tui -.->|"sends turns"| node_entry
node_desktop -.->|"connects"| node_entry
node_gateway -.->|"routes prompts"| node_turnloop
node_webhook -->|"receives events"| node_gateway
node_signal -->|"adapts messages"| node_gateway
node_entry -->|"runs"| node_turnloop
node_turnloop -->|"requests model"| node_providers
node_turnloop -.->|"dispatches tools"| node_tooling
node_turnloop -->|"uses memory"| node_memory
node_memory -->|"enables learning"| node_skills
node_turnloop -->|"spawns work"| node_subagents
node_turnloop -->|"uses environment"| node_backends
node_gateway -->|"delivers jobs"| node_scheduler
node_turnloop -->|"records runs"| node_trajectory
node_tooling -.->|"uses language services"| node_lsp

click node_cli "https://github.com/skygod07/hermes-agent/blob/main/cli.py"
click node_tui "https://github.com/skygod07/hermes-agent/blob/main/ui-tui/src/app.tsx"
click node_desktop "https://github.com/skygod07/hermes-agent/blob/main/apps/desktop/src/app/desktop-controller.tsx"
click node_gateway "https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/base.py"
click node_webhook "https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/webhook.py"
click node_signal "https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/signal.py"
click node_entry "https://github.com/skygod07/hermes-agent/blob/main/run_agent.py"
click node_turnloop "https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py"
click node_providers "https://github.com/skygod07/hermes-agent/blob/main/agent/model_metadata.py"
click node_tooling "https://github.com/skygod07/hermes-agent/blob/main/tools/terminal_tool.py"
click node_memory "https://github.com/skygod07/hermes-agent/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/skygod07/hermes-agent/blob/main/agent/skill_commands.py"
click node_scheduler "https://github.com/skygod07/hermes-agent/blob/main/gateway/config.py"
click node_subagents "https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py"
click node_backends "https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py"
click node_trajectory "https://github.com/skygod07/hermes-agent/blob/main/agent/trajectory.py"
click node_lsp "https://github.com/skygod07/hermes-agent/blob/main/agent/lsp/manager.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_cli,node_tui,node_desktop,node_user toneBlue
class node_entry,node_turnloop toneAmber
class node_tooling,node_memory,node_skills toneMint
class node_gateway,node_webhook,node_signal,node_providers toneRose
class node_scheduler,node_subagents,node_backends,node_trajectory,node_lsp toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/skygod07/hermes-agent/blob/main/cli.py): `cli.py`
- [Terminal UI](https://github.com/skygod07/hermes-agent/blob/main/ui-tui/src/app.tsx): `ui-tui/src/app.tsx`
- [Desktop App](https://github.com/skygod07/hermes-agent/blob/main/apps/desktop/src/app/desktop-controller.tsx): `apps/desktop/src/app/desktop-controller.tsx`

### Agent Runtime

- [Agent Entry](https://github.com/skygod07/hermes-agent/blob/main/run_agent.py): `run_agent.py`
- [Conversation Loop](https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`

### Tools and Learning

- [Tool Execution](https://github.com/skygod07/hermes-agent/blob/main/tools/terminal_tool.py): `tools/terminal_tool.py`
- [Memory Manager](https://github.com/skygod07/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skill Learning](https://github.com/skygod07/hermes-agent/blob/main/agent/skill_commands.py): `agent/skill_commands.py`

### Channels and Providers

- [Messaging Gateway](https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/base.py): `gateway/platforms/base.py`
- [Webhook Adapter](https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/webhook.py): `gateway/platforms/webhook.py`
- [Signal Adapter](https://github.com/skygod07/hermes-agent/blob/main/gateway/platforms/signal.py): `gateway/platforms/signal.py`
- [Model Providers](https://github.com/skygod07/hermes-agent/blob/main/agent/model_metadata.py): `agent/model_metadata.py`

### Execution and Research

- [Scheduled Jobs](https://github.com/skygod07/hermes-agent/blob/main/gateway/config.py): `gateway/config.py`
- [Subagents](https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Execution Backends](https://github.com/skygod07/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Trajectory Research](https://github.com/skygod07/hermes-agent/blob/main/agent/trajectory.py): `agent/trajectory.py`
- [Language Services](https://github.com/skygod07/hermes-agent/blob/main/agent/lsp/manager.py): `agent/lsp/manager.py`

### Other components

- **User**

## Connections

- User → CLI: prompts (evidence: `README.md`)
- User → Terminal UI: prompts (evidence: `README.md`)
- User → Desktop App: uses (evidence: `README.md`)
- User → Messaging Gateway: messages (evidence: `README.md`)
- CLI → Agent Entry: starts (evidence: `README.md`)
- Terminal UI → Agent Entry: sends turns
- Desktop App → Agent Entry: connects
- Messaging Gateway → Conversation Loop: routes prompts
- Webhook Adapter → Messaging Gateway: receives events (evidence: `gateway/platforms/webhook.py`)
- Signal Adapter → Messaging Gateway: adapts messages (evidence: `gateway/platforms/signal.py`)
- Agent Entry → Conversation Loop: runs (evidence: `agent/conversation_loop.py`)
- Conversation Loop → Model Providers: requests model (evidence: `agent/conversation_loop.py`)
- Conversation Loop → Tool Execution: dispatches tools
- Conversation Loop → Memory Manager: uses memory (evidence: `agent/conversation_loop.py`)
- Memory Manager → Skill Learning: enables learning (evidence: `agent/memory_manager.py`)
- Conversation Loop → Subagents: spawns work (evidence: `README.md`)
- Conversation Loop → Execution Backends: uses environment (evidence: `README.md`)
- Messaging Gateway → Scheduled Jobs: delivers jobs (evidence: `README.md`)
- Conversation Loop → Trajectory Research: records runs (evidence: `agent/conversation_loop.py`)
- Tool Execution → Language Services: uses language services
