# m0at/hermes-lite architecture

> Architecture diagram of the GitHub repository m0at/hermes-lite, 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/m0at/hermes-lite
- Repository: https://github.com/m0at/hermes-lite

## Overview

hermes-lite is a local-first coding agent with CLI and native Rust TUI entry points. Its main workflow accepts a prompt, builds and sends model context, interprets the response, dispatches tools, and returns results; the TUI can run multiple Python agents through a subprocess protocol. Separate branches provide persistent sessions, shared memory, skills, terminal backends, and Rust-assisted loop control. README statements establish the product-level workflows; source excerpts and the index support selected implementation links, so unsampled subsystem internals are represented conservatively.

Main entry points: [`src/run_agent.py`](https://github.com/m0at/hermes-lite/blob/main/src/run_agent.py) (Agent loop), [`hermes_tui/src/main.rs`](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/main.rs) (Native TUI), [`src/tools/terminal_tool.py`](https://github.com/m0at/hermes-lite/blob/main/src/tools/terminal_tool.py) (Terminal execution), [`src/hermes_agent.py`](https://github.com/m0at/hermes-lite/blob/main/src/hermes_agent.py) (Hermes agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI and REPL<br/>[cli.py]"]
  node_cli_entry["CLI entry<br/>[main.py]"]
  node_tui["Native TUI<br/>[main.rs]"]
  node_tui_state["Pane state<br/>[app.rs]"]
  node_tui_render["TUI rendering<br/>[ui.rs]"]
  node_mentions["Mentions and routing<br/>[mention.rs]"]
  node_subprocess["Agent subprocess<br/>[subprocess.rs]"]
  node_protocol["JSON protocol<br/>[protocol.rs]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_custom["Hermes agent<br/>[hermes_agent.py]"]
  node_loop["Agent loop<br/>[run_agent.py]"]
  node_loop_driver["FSM loop driver<br/>[loop_driver.py]"]
  node_prompt["Prompt building<br/>[prompt_builder.py]"]
  node_compression["Context compression"]
  node_tool_parse["Tool-call parsing"]
  node_model["Model service"]
end

subgraph group_tools["Tools and integrations"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_terminal["Terminal execution<br/>[terminal_tool.py]"]
  node_terminal_env["Terminal backends"]
  node_file_tools["File operations<br/>[file_operations.py]"]
  node_memory["Persistent memory<br/>[memory_tool.py]"]
  node_skills["Skills system<br/>[skill_tools.py]"]
end

subgraph group_state["State and Rust"]
  node_fsm["Rust FSM<br/>[lib.rs]"]
  node_session_db[("Session database<br/>[session_db.rs]")]
  node_shared_fs[("Shared memory files")]
end

node_user(("User"))

node_user -->|"starts chat"| node_cli_entry
node_cli_entry -->|"starts REPL"| node_cli
node_user -->|"starts TUI"| node_tui
node_tui -->|"updates panes"| node_tui_state
node_tui_render -->|"renders state"| node_tui_state
node_tui -.->|"routes mentions"| node_mentions
node_tui -->|"spawns agents"| node_subprocess
node_tui -->|"exchanges JSON"| node_protocol
node_subprocess -->|"runs process"| node_agent_custom
node_cli -->|"starts agent"| node_agent_custom
node_agent_custom -->|"extends runner"| node_loop
node_loop -->|"uses loop driver"| node_loop_driver
node_loop_driver -->|"drives states"| node_fsm
node_loop -->|"builds context"| node_prompt
node_loop -->|"requests completion"| node_model
node_loop -->|"compresses context"| node_compression
node_loop -->|"parses calls"| node_tool_parse
node_loop -->|"dispatches tools"| node_registry
node_registry -->|"registers tool"| node_terminal
node_terminal -->|"selects backend"| node_terminal_env
node_terminal -->|"uses file tools"| node_file_tools
node_loop -->|"provides memory"| node_memory
node_loop -->|"offers skills"| node_skills
node_loop -->|"stores sessions"| node_session_db
node_memory -->|"reads and writes"| node_shared_fs

click node_cli "https://github.com/m0at/hermes-lite/blob/main/src/cli.py"
click node_cli_entry "https://github.com/m0at/hermes-lite/blob/main/src/hermes_cli/main.py"
click node_tui "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/main.rs"
click node_tui_state "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/app.rs"
click node_tui_render "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/ui.rs"
click node_mentions "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/mention.rs"
click node_subprocess "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/subprocess.rs"
click node_protocol "https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/protocol.rs"
click node_agent_custom "https://github.com/m0at/hermes-lite/blob/main/src/hermes_agent.py"
click node_loop "https://github.com/m0at/hermes-lite/blob/main/src/run_agent.py"
click node_loop_driver "https://github.com/m0at/hermes-lite/blob/main/src/agent/loop_driver.py"
click node_prompt "https://github.com/m0at/hermes-lite/blob/main/src/agent/prompt_builder.py"
click node_compression "https://github.com/m0at/hermes-lite/blob/main/src/agent/context_compressor.py"
click node_tool_parse "https://github.com/m0at/hermes-lite/blob/main/src/agent/tool_call_parser.py"
click node_registry "https://github.com/m0at/hermes-lite/blob/main/src/tools/registry.py"
click node_terminal "https://github.com/m0at/hermes-lite/blob/main/src/tools/terminal_tool.py"
click node_terminal_env "https://github.com/m0at/hermes-lite/tree/main/src/tools/environments"
click node_file_tools "https://github.com/m0at/hermes-lite/blob/main/src/tools/file_operations.py"
click node_memory "https://github.com/m0at/hermes-lite/blob/main/src/tools/memory_tool.py"
click node_skills "https://github.com/m0at/hermes-lite/blob/main/src/tools/skill_tools.py"
click node_fsm "https://github.com/m0at/hermes-lite/blob/main/hermes_rs/src/lib.rs"
click node_session_db "https://github.com/m0at/hermes-lite/blob/main/hermes_rs/src/session_db.rs"

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_cli_entry,node_tui,node_tui_state,node_tui_render,node_mentions,node_subprocess,node_protocol,node_user toneBlue
class node_agent_custom,node_loop,node_loop_driver,node_prompt,node_compression,node_tool_parse,node_model toneAmber
class node_registry,node_terminal,node_terminal_env,node_file_tools,node_memory,node_skills toneMint
class node_fsm,node_session_db,node_shared_fs toneRose
```

## Components

### User interfaces

- [CLI and REPL](https://github.com/m0at/hermes-lite/blob/main/src/cli.py): `src/cli.py`
- [CLI entry](https://github.com/m0at/hermes-lite/blob/main/src/hermes_cli/main.py): `src/hermes_cli/main.py`
- [Native TUI](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/main.rs): `hermes_tui/src/main.rs`
- [Pane state](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/app.rs): `hermes_tui/src/app.rs`
- [TUI rendering](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/ui.rs): `hermes_tui/src/ui.rs`
- [Mentions and routing](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/mention.rs): `hermes_tui/src/mention.rs`
- [Agent subprocess](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/subprocess.rs): `hermes_tui/src/subprocess.rs`
- [JSON protocol](https://github.com/m0at/hermes-lite/blob/main/hermes_tui/src/protocol.rs): `hermes_tui/src/protocol.rs`

### Agent runtime

- [Hermes agent](https://github.com/m0at/hermes-lite/blob/main/src/hermes_agent.py): `src/hermes_agent.py`
- [Agent loop](https://github.com/m0at/hermes-lite/blob/main/src/run_agent.py): `src/run_agent.py`
- [FSM loop driver](https://github.com/m0at/hermes-lite/blob/main/src/agent/loop_driver.py): `src/agent/loop_driver.py`
- [Prompt building](https://github.com/m0at/hermes-lite/blob/main/src/agent/prompt_builder.py): `src/agent/prompt_builder.py`
- [Context compression](https://github.com/m0at/hermes-lite/blob/main/src/agent/context_compressor.py): `src/agent/context_compressor.py`
- [Tool-call parsing](https://github.com/m0at/hermes-lite/blob/main/src/agent/tool_call_parser.py): `src/agent/tool_call_parser.py`
- **Model service**

### Tools and integrations

- [Tool registry](https://github.com/m0at/hermes-lite/blob/main/src/tools/registry.py): `src/tools/registry.py`
- [Terminal execution](https://github.com/m0at/hermes-lite/blob/main/src/tools/terminal_tool.py): `src/tools/terminal_tool.py`
- [Terminal backends](https://github.com/m0at/hermes-lite/tree/main/src/tools/environments): `src/tools/environments`
- [File operations](https://github.com/m0at/hermes-lite/blob/main/src/tools/file_operations.py): `src/tools/file_operations.py`
- [Persistent memory](https://github.com/m0at/hermes-lite/blob/main/src/tools/memory_tool.py): `src/tools/memory_tool.py`
- [Skills system](https://github.com/m0at/hermes-lite/blob/main/src/tools/skill_tools.py): `src/tools/skill_tools.py`

### State and Rust

- [Rust FSM](https://github.com/m0at/hermes-lite/blob/main/hermes_rs/src/lib.rs): `hermes_rs/src/lib.rs`
- [Session database](https://github.com/m0at/hermes-lite/blob/main/hermes_rs/src/session_db.rs): `hermes_rs/src/session_db.rs`
- **Shared memory files**

### Other components

- **User**

## Connections

- User → CLI entry: starts chat (evidence: `README.md`)
- CLI entry → CLI and REPL: starts REPL (evidence: `src/hermes_cli/main.py`)
- User → Native TUI: starts TUI (evidence: `README.md`)
- Native TUI → Pane state: updates panes (evidence: `hermes_tui/src/main.rs`)
- TUI rendering → Pane state: renders state (evidence: `hermes_tui/src/ui.rs`)
- Native TUI → Mentions and routing: routes mentions (evidence: `README.md`)
- Native TUI → Agent subprocess: spawns agents (evidence: `README.md`)
- Native TUI → JSON protocol: exchanges JSON (evidence: `README.md`)
- Agent subprocess → Hermes agent: runs process (evidence: `README.md`)
- CLI and REPL → Hermes agent: starts agent (evidence: `src/hermes_agent.py`)
- Hermes agent → Agent loop: extends runner (evidence: `src/hermes_agent.py`)
- Agent loop → FSM loop driver: uses loop driver (evidence: `README.md`)
- FSM loop driver → Rust FSM: drives states (evidence: `README.md`)
- Agent loop → Prompt building: builds context (evidence: `src/run_agent.py`)
- Agent loop → Model service: requests completion (evidence: `README.md`)
- Agent loop → Context compression: compresses context (evidence: `src/run_agent.py`)
- Agent loop → Tool-call parsing: parses calls (evidence: `src/run_agent.py`)
- Agent loop → Tool registry: dispatches tools (evidence: `src/run_agent.py`)
- Tool registry → Terminal execution: registers tool (evidence: `src/tools/terminal_tool.py`)
- Terminal execution → Terminal backends: selects backend (evidence: `src/tools/terminal_tool.py`)
- Terminal execution → File operations: uses file tools (evidence: `src/tools/terminal_tool.py`)
- Agent loop → Persistent memory: provides memory (evidence: `README.md`)
- Agent loop → Skills system: offers skills (evidence: `README.md`)
- Agent loop → Session database: stores sessions (evidence: `src/run_agent.py`)
- Persistent memory → Shared memory files: reads and writes (evidence: `README.md`)
