# maestro2903/friday architecture

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

- Interactive diagram: https://gitdiagram.com/maestro2903/friday
- Repository: https://github.com/maestro2903/friday

## Overview

Hermes Agent is a multi-interface, self-improving AI agent. Users chat through the CLI/TUI or messaging platforms; requests enter a session, run through the agent loop and model, and may invoke tools before returning a response. The README also documents memory and skill learning, scheduled jobs, subagents, remote terminal backends, voice, and research workflows. Those broader capability links are documented in the README; source excerpts are limited, so the diagram avoids implying unverified internal calls.

Main entry points: [`agent/conversation_loop.py`](https://github.com/maestro2903/friday/blob/main/agent/conversation_loop.py) (Conversation Loop), [`gateway/platforms/base.py`](https://github.com/maestro2903/friday/blob/main/gateway/platforms/base.py) (Messaging Gateway), [`agent/tool_executor.py`](https://github.com/maestro2903/friday/blob/main/agent/tool_executor.py) (Tool Execution), [`hermes_cli/console_engine.py`](https://github.com/maestro2903/friday/blob/main/hermes_cli/console_engine.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[console_engine.py]"]
  node_tui["Terminal UI<br/>[turnController.ts]"]
  node_desktop["Desktop App"]
end

subgraph group_runtime["Agent Runtime"]
  node_session["Session Handling<br/>[session.py]"]
  node_loop["Conversation Loop"]
  node_context["Prompt And Context<br/>[prompt_builder.py]"]
  node_models["Model Providers"]
end

subgraph group_tools["Tools And Delegation"]
  node_tooling["Tool Execution<br/>[tool_executor.py]"]
  node_terminals["Terminal Backends"]
  node_subagents["Subagents"]
  node_rpc["Tool RPC<br/>[oneshot.py]"]
end

subgraph group_learning["Learning And Memory"]
  node_memory[("Agent Memory<br/>[memory_manager.py]")]
  node_skills["Skill Learning<br/>[skill_commands.py]"]
  node_search["Session Search"]
  node_research["Trajectory Research<br/>[trajectory.py]"]
end

subgraph group_channels["Channels And Automation"]
  node_gateway["Messaging Gateway<br/>[base.py]"]
  node_cron["Scheduled Jobs<br/>[console_engine.py]"]
  node_voice["Voice Features"]
  node_platforms["Messaging Platforms"]
end

node_user(("User"))

node_user -->|"starts chat"| node_cli
node_user -->|"starts chat"| node_tui
node_user -->|"uses app"| node_desktop
node_user -->|"sends messages"| node_platforms
node_cli -.->|"starts agent"| node_loop
node_tui -->|"calls gateway"| node_gateway
node_desktop -.->|"uses gateway"| node_gateway
node_platforms -->|"routes messages"| node_gateway
node_gateway -->|"maintains sessions"| node_session
node_session -.->|"runs turns"| node_loop
node_loop -.->|"builds context"| node_context
node_loop -.->|"requests completion"| node_models
node_loop -.->|"dispatches tools"| node_tooling
node_tooling -->|"uses backends"| node_terminals
node_tooling -->|"spawns agents"| node_subagents
node_subagents -->|"calls tools"| node_rpc
node_loop -.->|"uses memory"| node_memory
node_loop -->|"curates skills"| node_skills
node_memory -->|"recalls sessions"| node_search
node_gateway -->|"delivers scheduled jobs"| node_cron
node_loop -->|"transcribes voice memos"| node_voice
node_loop -->|"generates trajectories"| node_research

click node_cli "https://github.com/maestro2903/friday/blob/main/hermes_cli/console_engine.py"
click node_tui "https://github.com/maestro2903/friday/blob/main/ui-tui/src/app/turnController.ts"
click node_desktop "https://github.com/maestro2903/friday/blob/main/apps/desktop/src/app/desktop-controller.tsx"
click node_gateway "https://github.com/maestro2903/friday/blob/main/gateway/platforms/base.py"
click node_session "https://github.com/maestro2903/friday/blob/main/gateway/session.py"
click node_loop "https://github.com/maestro2903/friday/blob/main/agent/conversation_loop.py"
click node_context "https://github.com/maestro2903/friday/blob/main/agent/prompt_builder.py"
click node_models "https://github.com/maestro2903/friday/blob/main/agent/anthropic_adapter.py"
click node_tooling "https://github.com/maestro2903/friday/blob/main/agent/tool_executor.py"
click node_terminals "https://github.com/maestro2903/friday/tree/main/tools"
click node_subagents "https://github.com/maestro2903/friday/blob/main/agent/agent_runtime_helpers.py"
click node_rpc "https://github.com/maestro2903/friday/blob/main/agent/oneshot.py"
click node_memory "https://github.com/maestro2903/friday/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/maestro2903/friday/blob/main/agent/skill_commands.py"
click node_search "https://github.com/maestro2903/friday/tree/main/agent"
click node_cron "https://github.com/maestro2903/friday/blob/main/hermes_cli/console_engine.py"
click node_voice "https://github.com/maestro2903/friday/blob/main/agent/transcription_provider.py"
click node_research "https://github.com/maestro2903/friday/blob/main/agent/trajectory.py"
click node_platforms "https://github.com/maestro2903/friday/tree/main/gateway/platforms"

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_session,node_loop,node_context,node_models toneAmber
class node_tooling,node_terminals,node_subagents,node_rpc toneMint
class node_memory,node_skills,node_search,node_research toneRose
class node_gateway,node_cron,node_voice,node_platforms toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/maestro2903/friday/blob/main/hermes_cli/console_engine.py): `hermes_cli/console_engine.py`
- [Terminal UI](https://github.com/maestro2903/friday/blob/main/ui-tui/src/app/turnController.ts): `ui-tui/src/app/turnController.ts`
- [Desktop App](https://github.com/maestro2903/friday/blob/main/apps/desktop/src/app/desktop-controller.tsx): `apps/desktop/src/app/desktop-controller.tsx`

### Agent Runtime

- [Session Handling](https://github.com/maestro2903/friday/blob/main/gateway/session.py): `gateway/session.py`
- [Conversation Loop](https://github.com/maestro2903/friday/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Prompt And Context](https://github.com/maestro2903/friday/blob/main/agent/prompt_builder.py): `agent/prompt_builder.py`
- [Model Providers](https://github.com/maestro2903/friday/blob/main/agent/anthropic_adapter.py): `agent/anthropic_adapter.py`

### Tools And Delegation

- [Tool Execution](https://github.com/maestro2903/friday/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Terminal Backends](https://github.com/maestro2903/friday/tree/main/tools): `tools`
- [Subagents](https://github.com/maestro2903/friday/blob/main/agent/agent_runtime_helpers.py): `agent/agent_runtime_helpers.py`
- [Tool RPC](https://github.com/maestro2903/friday/blob/main/agent/oneshot.py): `agent/oneshot.py`

### Learning And Memory

- [Agent Memory](https://github.com/maestro2903/friday/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skill Learning](https://github.com/maestro2903/friday/blob/main/agent/skill_commands.py): `agent/skill_commands.py`
- [Session Search](https://github.com/maestro2903/friday/tree/main/agent): `agent`
- [Trajectory Research](https://github.com/maestro2903/friday/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Channels And Automation

- [Messaging Gateway](https://github.com/maestro2903/friday/blob/main/gateway/platforms/base.py): `gateway/platforms/base.py`
- [Scheduled Jobs](https://github.com/maestro2903/friday/blob/main/hermes_cli/console_engine.py): `hermes_cli/console_engine.py`
- [Voice Features](https://github.com/maestro2903/friday/blob/main/agent/transcription_provider.py): `agent/transcription_provider.py`
- [Messaging Platforms](https://github.com/maestro2903/friday/tree/main/gateway/platforms): `gateway/platforms`

### Other components

- **User**

## Connections

- User → CLI: starts chat (evidence: `README.md`)
- User → Terminal UI: starts chat (evidence: `README.md`)
- User → Desktop App: uses app (evidence: `README.md`)
- User → Messaging Platforms: sends messages (evidence: `README.md`)
- CLI → Conversation Loop: starts agent
- Terminal UI → Messaging Gateway: calls gateway (evidence: `README.md`)
- Desktop App → Messaging Gateway: uses gateway
- Messaging Platforms → Messaging Gateway: routes messages (evidence: `README.md`)
- Messaging Gateway → Session Handling: maintains sessions (evidence: `README.md`)
- Session Handling → Conversation Loop: runs turns
- Conversation Loop → Prompt And Context: builds context
- Conversation Loop → Model Providers: requests completion
- Conversation Loop → Tool Execution: dispatches tools
- Tool Execution → Terminal Backends: uses backends (evidence: `README.md`)
- Tool Execution → Subagents: spawns agents (evidence: `README.md`)
- Subagents → Tool RPC: calls tools (evidence: `README.md`)
- Conversation Loop → Agent Memory: uses memory
- Conversation Loop → Skill Learning: curates skills (evidence: `README.md`)
- Agent Memory → Session Search: recalls sessions (evidence: `README.md`)
- Messaging Gateway → Scheduled Jobs: delivers scheduled jobs (evidence: `README.md`)
- Conversation Loop → Voice Features: transcribes voice memos (evidence: `README.md`)
- Conversation Loop → Trajectory Research: generates trajectories (evidence: `README.md`)
