# sda1-hacker/humbert-agent architecture

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

- Interactive diagram: https://gitdiagram.com/sda1-hacker/humbert-agent
- Repository: https://github.com/sda1-hacker/humbert-agent

## Overview

Humbert Agent is a local-first desktop assistant. The primary workflow is a user chat turn: the Vue interface calls Wails services, which coordinate the Go runtime, context construction, configured model, tools, and session transcript before returning streamed activity and a result. Separate product branches manage workspaces, Skills/MCP extensions, approvals, scheduled and proactive tasks, search, and backup. Wiring is based on the README’s architecture and capability descriptions; sampled source confirms selected permission, context, task, MCP, and service behaviors, but not every runtime call site.

Main entry points: [`internal/services`](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/services) (Wails services), [`internal/runtime`](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/runtime) (Eino runtime), [`internal/tools`](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/tools) (Agent tools), [`internal/searchindex`](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/searchindex) (Search indexes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_frontend["Vue desktop UI"]
  node_wails["Wails services"]
end

subgraph group_core["Turn execution"]
  node_application["Core assembly"]
  node_agent[("Agent profiles")]
  node_session[("Sessions")]
  node_transcript[("Turn history")]
  node_runtime["Eino runtime"]
  node_context["Context engine"]
  node_model["Model routing"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Agent tools"]
  node_workspace["Workspace access"]
  node_skills["Skills"]
  node_mcp["MCP connectors"]
end

subgraph group_operations["Tasks and data"]
  node_tasks[("Scheduled tasks")]
  node_proactive["Proactive manager"]
  node_search[("Search indexes")]
  node_backup["Encrypted backup"]
end

subgraph group_security["Safety controls"]
  node_approval["Approvals"]
  node_permission[("Permission policy")]
  node_sandbox["Execution sandbox"]
end

node_user(("User"))
node_provider["Model provider"]

node_user -->|"sends requests"| node_frontend
node_frontend -->|"calls services"| node_wails
node_wails -->|"uses core"| node_application
node_wails -->|"submits turns"| node_runtime
node_wails -->|"manages sessions"| node_session
node_application -->|"configures"| node_agent
node_runtime -->|"uses profile"| node_agent
node_runtime -->|"builds context"| node_context
node_context -->|"reads history"| node_transcript
node_runtime -->|"records turn"| node_transcript
node_runtime -->|"selects model"| node_model
node_model -->|"sends prompts"| node_provider
node_runtime -->|"dispatches calls"| node_tools
node_tools -->|"accesses files"| node_workspace
node_tools -->|"checks access"| node_permission
node_tools -->|"runs isolated"| node_sandbox
node_runtime -->|"requests approval"| node_approval
node_wails -->|"manages Skills"| node_skills
node_runtime -->|"uses selected"| node_skills
node_wails -->|"manages connectors"| node_mcp
node_runtime -->|"loads tools"| node_mcp
node_wails -->|"manages schedules"| node_tasks
node_tasks -->|"runs task"| node_runtime
node_proactive -->|"executes automation"| node_tasks
node_wails -->|"configures"| node_proactive
node_wails -->|"queries indexes"| node_search
node_search -->|"indexes messages"| node_transcript
node_search -->|"indexes documents"| node_workspace
node_wails -->|"requests backup"| node_backup

click node_frontend "https://github.com/sda1-hacker/humbert-agent/tree/main/frontend/src"
click node_wails "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/services"
click node_application "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/app"
click node_agent "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/agents"
click node_session "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/sessions"
click node_transcript "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/transcript"
click node_runtime "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/runtime"
click node_context "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/contextengine"
click node_model "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/models"
click node_tools "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/tools"
click node_workspace "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/workspace"
click node_skills "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/skills"
click node_mcp "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/mcp"
click node_approval "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/approval"
click node_permission "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/permission"
click node_sandbox "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/sandbox"
click node_tasks "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/tasks"
click node_proactive "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/proactive"
click node_search "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/searchindex"
click node_backup "https://github.com/sda1-hacker/humbert-agent/tree/main/internal/databackup"

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_frontend,node_wails,node_user toneBlue
class node_application,node_agent,node_session,node_transcript,node_runtime,node_context,node_model toneAmber
class node_tools,node_workspace,node_skills,node_mcp toneMint
class node_tasks,node_proactive,node_search,node_backup toneRose
class node_approval,node_permission,node_sandbox,node_provider toneIndigo
```

## Components

### Desktop interface

- [Vue desktop UI](https://github.com/sda1-hacker/humbert-agent/tree/main/frontend/src): `frontend/src`
- [Wails services](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/services): `internal/services`

### Turn execution

- [Core assembly](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/app): `internal/app`
- [Agent profiles](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/agents): `internal/agents`
- [Sessions](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/sessions): `internal/sessions`
- [Turn history](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/transcript): `internal/transcript`
- [Eino runtime](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/runtime): `internal/runtime`
- [Context engine](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/contextengine): `internal/contextengine`
- [Model routing](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/models): `internal/models`

### Agent capabilities

- [Agent tools](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/tools): `internal/tools`
- [Workspace access](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/workspace): `internal/workspace`
- [Skills](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/skills): `internal/skills`
- [MCP connectors](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/mcp): `internal/mcp`

### Tasks and data

- [Scheduled tasks](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/tasks): `internal/tasks`
- [Proactive manager](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/proactive): `internal/proactive`
- [Search indexes](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/searchindex): `internal/searchindex`
- [Encrypted backup](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/databackup): `internal/databackup`

### Safety controls

- [Approvals](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/approval): `internal/approval`
- [Permission policy](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/permission): `internal/permission`
- [Execution sandbox](https://github.com/sda1-hacker/humbert-agent/tree/main/internal/sandbox): `internal/sandbox`

### Other components

- **User**
- **Model provider**

## Connections

- User → Vue desktop UI: sends requests
- Vue desktop UI → Wails services: calls services
- Wails services → Core assembly: uses core
- Wails services → Eino runtime: submits turns
- Wails services → Sessions: manages sessions
- Core assembly → Agent profiles: configures
- Eino runtime → Agent profiles: uses profile
- Eino runtime → Context engine: builds context
- Context engine → Turn history: reads history
- Eino runtime → Turn history: records turn
- Eino runtime → Model routing: selects model
- Model routing → Model provider: sends prompts
- Eino runtime → Agent tools: dispatches calls
- Agent tools → Workspace access: accesses files
- Agent tools → Permission policy: checks access
- Agent tools → Execution sandbox: runs isolated
- Eino runtime → Approvals: requests approval
- Wails services → Skills: manages Skills
- Eino runtime → Skills: uses selected
- Wails services → MCP connectors: manages connectors
- Eino runtime → MCP connectors: loads tools
- Wails services → Scheduled tasks: manages schedules
- Scheduled tasks → Eino runtime: runs task
- Proactive manager → Scheduled tasks: executes automation
- Wails services → Proactive manager: configures
- Wails services → Search indexes: queries indexes
- Search indexes → Turn history: indexes messages
- Search indexes → Workspace access: indexes documents
- Wails services → Encrypted backup: requests backup