# helloeveryboby/butler architecture

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

- Interactive diagram: https://gitdiagram.com/helloeveryboby/butler
- Repository: https://github.com/helloeveryboby/butler

## Overview

Butler is a local-first personal assistant, with Python coordinating conversational AI, skills, automation, memory, and optional native services. A typical user flow enters through the assistant or terminal UI, passes through intent/agent handling, and reaches a skill or workflow execution result. The repository also documents voice, document, storage, hardware, and hybrid-language capabilities. Some connections below come from README descriptions or file references in the source index; unsampled implementation details are not inferred as confirmed calls.

Main entry points: [`butler/butler_app.py`](https://github.com/helloeveryboby/butler/blob/main/butler/butler_app.py) (Assistant runtime), [`butler/agent/executor.py`](https://github.com/helloeveryboby/butler/blob/main/butler/agent/executor.py) (Action executor), [`butler/workflow/engine.py`](https://github.com/helloeveryboby/butler/blob/main/butler/workflow/engine.py) (Workflow engine), [`butler/tui/main.py`](https://github.com/helloeveryboby/butler/blob/main/butler/tui/main.py) (Terminal interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_terminal["Terminal interface<br/>[main.py]"]
  node_command_catalog["Command catalog<br/>[command_catalog.py]"]
  node_command_panel["Command panel<br/>[CommandPanel.py]"]
  node_voice["Voice service<br/>[voice_service.py]"]
end

subgraph group_orchestration["Assistant orchestration"]
  node_assistant["Assistant runtime<br/>[butler_app.py]"]
  node_environment["Runtime environment<br/>[environment.py]"]
  node_nlu["Intent understanding<br/>[nlu_service.py]"]
  node_agent["Agent planning<br/>[agent.py]"]
  node_executor["Action executor<br/>[executor.py]"]
  node_workflow["Workflow engine<br/>[engine.py]"]
  node_events["Event bus<br/>[event_bus.py]"]
end

subgraph group_capabilities["Skills and capabilities"]
  node_skills["Skill manager<br/>[skill_manager.py]"]
  node_packages["Package loader<br/>[loader.py]"]
  node_documents["Document tools<br/>[file_converter.py]"]
  node_translation["Translation engine<br/>[engine.py]"]
end

subgraph group_state["Memory and state"]
  node_memory[("Long-term memory<br/>[memory_engine.py]")]
  node_data_storage[("Plugin data storage<br/>[data_storage.py]")]
  node_dream["Dream engine<br/>[dream_engine.py]"]
  node_self_healing["Self-healing<br/>[self_healing.py]"]
end

subgraph group_integrations["System integrations"]
  node_hybrid["Hybrid link<br/>[hybrid_link.py]"]
  node_hardware["Hardware manager"]
  node_storage_hub["Cloud storage hub<br/>[storage_hub.py]"]
end

node_user(("User"))
node_external_services(("External services"))

node_user -->|"starts"| node_assistant
node_user -->|"uses"| node_terminal
node_assistant -->|"initializes"| node_environment
node_assistant -->|"uses"| node_events
node_assistant -->|"uses"| node_command_panel
node_assistant -->|"uses"| node_voice
node_assistant -->|"uses"| node_nlu
node_assistant -->|"uses"| node_skills
node_assistant -->|"uses"| node_memory
node_terminal -->|"uses"| node_command_catalog
node_user -->|"speaks to"| node_voice
node_nlu -.->|"routes intent"| node_agent
node_agent -->|"plans actions"| node_executor
node_executor -->|"loads packages"| node_packages
node_workflow -->|"executes steps"| node_executor
node_workflow -->|"loads packages"| node_packages
node_skills -.->|"offers skills"| node_user
node_assistant -.->|"integrates memory"| node_dream
node_assistant -.->|"supports recovery"| node_self_healing
node_assistant -.->|"uses hybrid link"| node_hybrid
node_assistant -.->|"supports hardware"| node_hardware
node_assistant -.->|"offers document tools"| node_documents
node_documents -.->|"includes translation"| node_translation
node_assistant -.->|"supports cloud storage"| node_storage_hub
node_assistant -->|"stores plugin data"| node_data_storage
node_memory -.->|"optional Redis"| node_external_services
node_storage_hub -.->|"connects storage"| node_external_services

click node_assistant "https://github.com/helloeveryboby/butler/blob/main/butler/butler_app.py"
click node_environment "https://github.com/helloeveryboby/butler/blob/main/butler/core/environment.py"
click node_nlu "https://github.com/helloeveryboby/butler/blob/main/butler/core/nlu_service.py"
click node_agent "https://github.com/helloeveryboby/butler/blob/main/butler/agent/agent.py"
click node_executor "https://github.com/helloeveryboby/butler/blob/main/butler/agent/executor.py"
click node_workflow "https://github.com/helloeveryboby/butler/blob/main/butler/workflow/engine.py"
click node_events "https://github.com/helloeveryboby/butler/blob/main/butler/core/event_bus.py"
click node_terminal "https://github.com/helloeveryboby/butler/blob/main/butler/tui/main.py"
click node_command_catalog "https://github.com/helloeveryboby/butler/blob/main/butler/tui/command_catalog.py"
click node_command_panel "https://github.com/helloeveryboby/butler/blob/main/butler/CommandPanel.py"
click node_voice "https://github.com/helloeveryboby/butler/blob/main/butler/core/voice_service.py"
click node_skills "https://github.com/helloeveryboby/butler/blob/main/butler/core/skill_manager.py"
click node_packages "https://github.com/helloeveryboby/butler/blob/main/butler/package_runtime/loader.py"
click node_documents "https://github.com/helloeveryboby/butler/blob/main/package/document/file_converter.py"
click node_translation "https://github.com/helloeveryboby/butler/blob/main/package/document/translate_system/engine.py"
click node_memory "https://github.com/helloeveryboby/butler/blob/main/butler/core/memory/memory_engine.py"
click node_data_storage "https://github.com/helloeveryboby/butler/blob/main/butler/data_storage.py"
click node_dream "https://github.com/helloeveryboby/butler/blob/main/butler/core/dream_engine.py"
click node_self_healing "https://github.com/helloeveryboby/butler/blob/main/butler/core/self_healing.py"
click node_hybrid "https://github.com/helloeveryboby/butler/blob/main/butler/core/hybrid_link.py"
click node_hardware "https://github.com/helloeveryboby/butler/blob/main/package/device/hardware_manager.py"
click node_storage_hub "https://github.com/helloeveryboby/butler/blob/main/package/storage_hub/storage_hub.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_terminal,node_command_catalog,node_command_panel,node_voice,node_user toneBlue
class node_assistant,node_environment,node_nlu,node_agent,node_executor,node_workflow,node_events toneAmber
class node_skills,node_packages,node_documents,node_translation toneMint
class node_memory,node_data_storage,node_dream,node_self_healing toneRose
class node_hybrid,node_hardware,node_storage_hub,node_external_services toneIndigo
```

## Components

### User interaction

- [Terminal interface](https://github.com/helloeveryboby/butler/blob/main/butler/tui/main.py): `butler/tui/main.py`
- [Command catalog](https://github.com/helloeveryboby/butler/blob/main/butler/tui/command_catalog.py): `butler/tui/command_catalog.py`
- [Command panel](https://github.com/helloeveryboby/butler/blob/main/butler/CommandPanel.py): `butler/CommandPanel.py`
- [Voice service](https://github.com/helloeveryboby/butler/blob/main/butler/core/voice_service.py): `butler/core/voice_service.py`

### Assistant orchestration

- [Assistant runtime](https://github.com/helloeveryboby/butler/blob/main/butler/butler_app.py): `butler/butler_app.py`
- [Runtime environment](https://github.com/helloeveryboby/butler/blob/main/butler/core/environment.py): `butler/core/environment.py`
- [Intent understanding](https://github.com/helloeveryboby/butler/blob/main/butler/core/nlu_service.py): `butler/core/nlu_service.py`
- [Agent planning](https://github.com/helloeveryboby/butler/blob/main/butler/agent/agent.py): `butler/agent/agent.py`
- [Action executor](https://github.com/helloeveryboby/butler/blob/main/butler/agent/executor.py): `butler/agent/executor.py`
- [Workflow engine](https://github.com/helloeveryboby/butler/blob/main/butler/workflow/engine.py): `butler/workflow/engine.py`
- [Event bus](https://github.com/helloeveryboby/butler/blob/main/butler/core/event_bus.py): `butler/core/event_bus.py`

### Skills and capabilities

- [Skill manager](https://github.com/helloeveryboby/butler/blob/main/butler/core/skill_manager.py): `butler/core/skill_manager.py`
- [Package loader](https://github.com/helloeveryboby/butler/blob/main/butler/package_runtime/loader.py): `butler/package_runtime/loader.py`
- [Document tools](https://github.com/helloeveryboby/butler/blob/main/package/document/file_converter.py): `package/document/file_converter.py`
- [Translation engine](https://github.com/helloeveryboby/butler/blob/main/package/document/translate_system/engine.py): `package/document/translate_system/engine.py`

### Memory and state

- [Long-term memory](https://github.com/helloeveryboby/butler/blob/main/butler/core/memory/memory_engine.py): `butler/core/memory/memory_engine.py`
- [Plugin data storage](https://github.com/helloeveryboby/butler/blob/main/butler/data_storage.py): `butler/data_storage.py`
- [Dream engine](https://github.com/helloeveryboby/butler/blob/main/butler/core/dream_engine.py): `butler/core/dream_engine.py`
- [Self-healing](https://github.com/helloeveryboby/butler/blob/main/butler/core/self_healing.py): `butler/core/self_healing.py`

### System integrations

- [Hybrid link](https://github.com/helloeveryboby/butler/blob/main/butler/core/hybrid_link.py): `butler/core/hybrid_link.py`
- [Hardware manager](https://github.com/helloeveryboby/butler/blob/main/package/device/hardware_manager.py): `package/device/hardware_manager.py`
- [Cloud storage hub](https://github.com/helloeveryboby/butler/blob/main/package/storage_hub/storage_hub.py): `package/storage_hub/storage_hub.py`

### Other components

- **User**
- **External services**

## Connections

- User → Assistant runtime: starts (evidence: `README.md`)
- User → Terminal interface: uses (evidence: `README.md`)
- Assistant runtime → Runtime environment: initializes (evidence: `butler/butler_app.py`)
- Assistant runtime → Event bus: uses (evidence: `butler/butler_app.py`)
- Assistant runtime → Command panel: uses (evidence: `butler/butler_app.py`)
- Assistant runtime → Voice service: uses (evidence: `butler/butler_app.py`)
- Assistant runtime → Intent understanding: uses (evidence: `butler/butler_app.py`)
- Assistant runtime → Skill manager: uses (evidence: `butler/butler_app.py`)
- Assistant runtime → Long-term memory: uses (evidence: `butler/butler_app.py`)
- Terminal interface → Command catalog: uses (evidence: `butler/tui/main.py`)
- User → Voice service: speaks to (evidence: `README.md`)
- Intent understanding → Agent planning: routes intent
- Agent planning → Action executor: plans actions (evidence: `butler/agent/agent.py`)
- Action executor → Package loader: loads packages (evidence: `butler/agent/executor.py`)
- Workflow engine → Action executor: executes steps (evidence: `butler/workflow/engine.py`)
- Workflow engine → Package loader: loads packages (evidence: `butler/workflow/engine.py`)
- Skill manager → User: offers skills (evidence: `README.md`)
- Assistant runtime → Dream engine: integrates memory (evidence: `README.md`)
- Assistant runtime → Self-healing: supports recovery (evidence: `README.md`)
- Assistant runtime → Hybrid link: uses hybrid link (evidence: `README.md`)
- Assistant runtime → Hardware manager: supports hardware (evidence: `README.md`)
- Assistant runtime → Document tools: offers document tools (evidence: `README.md`)
- Document tools → Translation engine: includes translation (evidence: `README.md`)
- Assistant runtime → Cloud storage hub: supports cloud storage (evidence: `README.md`)
- Assistant runtime → Plugin data storage: stores plugin data (evidence: `butler/butler_app.py`)
- Long-term memory → External services: optional Redis (evidence: `README.md`)
- Cloud storage hub → External services: connects storage (evidence: `package/storage_hub/storage_hub.py`)
