How hermes-agent Works: Architecture, System Design & Code Deep Dive

Project Overview

The Hermes Agent is a self-improving AI designed to learn and execute tasks. It solves the core problem of providing an intuitive and interactive interface for users to converse with, command, and configure a complex, learning AI agent. Users can interact with Hermes through a Terminal User Interface (TUI) for quick, command-line-like interactions, or a web dashboard for more visual configuration and analytics. The system enables users to give instructions, see the AI's thought process, watch it use tools, and even learn from its experiences to improve over time.

Category

agents

Difficulty

advanced

Tech Stack

Python, React

Tags

agent

How hermes-agent Works

The Hermes Agent is a self-improving AI designed to learn and execute tasks. It solves the core problem of providing an intuitive and interactive interface for users to converse with, command, and configure a complex, learning AI agent. Users can interact with Hermes through a Terminal User Interface (TUI) for quick, command-line-like interactions, or a web dashboard for more visual configuration and analytics. The system enables users to give instructions, see the AI's thought process, watch it use tools, and even learn from its experiences to improve over time.

Data Flow

Data in the Hermes Agent system flows primarily between the UI clients (TUI/Web) and the core AI agent backend, mediated by the `GatewayClient`. User input (text, commands) originates from `useComposerState` and `useSubmission`, then is sent via `GatewayClient` to the backend. The backend processes this input and streams back AI responses, reasoning, tool outputs, and status updates through the same `GatewayClient`. On the UI side, `turnController.ts` is the central receiver, distributing this incoming data to `turnStore.ts` (for the current conversation turn's state), `spawnHistoryStore.ts` (for subagent activities), and `overlayStore.ts` (for user prompts/confirmations). Configuration data, managed by `hermes_cli/config.py` on the backend, is synced to the TUI via `useConfigSync.ts` and can be updated through the web UI's `ConfigPage.tsx`. All communication adheres to the message formats defined in `gatewayTypes.ts` and `interfaces.ts`, ensuring both sides 'speak the same language'.

Key Modules & Components

• Conversational AI Interaction & Display: This module is the "display window" into the AI's mind in the terminal. It organizes and presents the AI's live thought process, how it uses tools, and its responses as they arrive, letting you see exactly how the AI is tackling tasks. It also tracks any smaller AI helpers (subagents) the main AI might use, and handles temporary interactive pop-ups during the conversation.
  Key files: ui-tui/src/app/turnController.ts, ui-tui/src/app/turnStore.ts, ui-tui/src/app/spawnHistoryStore.ts
• User Command & Input Management: This module is your voice to the AI. It takes everything you type in the terminal — your questions, instructions, and special "slash commands" (like /new or /model) — and makes sure the AI understands them. It also helps you type, manages your input history, and prepares your messages to be sent to the AI agent.
  Key files: ui-tui/src/app/useInputHandlers.ts, ui-tui/src/app/useComposerState.ts, ui-tui/src/app/useSubmission.ts
• Agent Session & Core Configuration: This module manages the overall lifecycle of your conversations and how the AI agent is set up. It lets you start fresh chats, resume old ones, clear the conversation history, and keeps track of important AI settings like the model it uses. It ensures the AI is always ready for your commands and remembers your preferences.
  Key files: ui-tui/src/app/useSessionLifecycle.ts, ui-tui/src/app/useConfigSync.ts
• Web-Based Agent Settings Interface: This module provides a visual web page where you can easily change the AI agent's settings without typing commands. It offers a friendly way to adjust parameters like the AI model, tool access, and other behaviors, making it simple to customize how your Hermes Agent works through a browser.
  Key files: web/src/pages/ConfigPage.tsx
• Inter-Application Communication Gateway: This module is the dedicated "messenger" that connects all parts of the Hermes Agent system. It ensures that the user interfaces (both the terminal and web) can reliably send commands to the powerful AI agent running separately, and then receive all of its real-time responses and updates back. It also defines the common language for these messages.
  Key files: ui-tui/src/gatewayClient.ts, ui-tui/src/app/gatewayContext.tsx, ui-tui/src/app/interfaces.ts
• User Interface Core Frameworks: This module provides the essential building blocks and overall structure for both the Terminal User Interface (TUI) and the Web Dashboard. It handles the initial launch, sets up the main layout, and ensures that all the different components within each interface can work together smoothly to create a functional application.
  Key files: ui-tui/src/app.tsx, ui-tui/src/app/useMainApp.ts, ui-tui/src/entry.tsx