# lokilogesh001/optimus architecture

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

- Interactive diagram: https://gitdiagram.com/lokilogesh001/optimus
- Repository: https://github.com/lokilogesh001/optimus

## Overview

OPTIMUS is a desktop personal AI assistant whose principal workflow is user command submission through the Control Center, orchestration into plans and delegated work, tool-mediated execution, and verification of outcomes. The repository also documents voice interaction, memory, workflows, model routing, and specialized agents; these remain distinct branches rather than being forced into one pipeline. Paths and edges are grounded in the README and SOURCE INDEX. Several subsystems are represented from documented capabilities despite unsampled implementations, so their internal links are omitted where evidence is unavailable.

Main entry points: [`core/orchestrator/orchestrator.py`](https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/orchestrator.py) (Central Orchestrator), [`core/orchestrator/tools.py`](https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/tools.py) (Tool Registry), [`gui/optimus/service_bridge.py`](https://github.com/lokilogesh001/optimus/blob/main/gui/optimus/service_bridge.py) (Service Bridge), [`core/workflows/engine.py`](https://github.com/lokilogesh001/optimus/blob/main/core/workflows/engine.py) (Workflow Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interaction"]
  node_control_center["Control Center"]
  node_service_bridge["Service Bridge<br/>[service_bridge.py]"]
  node_voice["Voice Interaction"]
end

subgraph group_coordination["Execution Coordination"]
  node_orchestrator["Central Orchestrator<br/>[orchestrator.py]"]
  node_events["Execution Events<br/>[events.py]"]
  node_planning["Adaptive Planning"]
  node_missions["Mission Engine<br/>[engine.py]"]
  node_workflows["Workflow Engine<br/>[engine.py]"]
  node_agents["Specialized Agents"]
end

subgraph group_intelligence["Intelligence"]
  node_intelligence_gateway["Model Gateway"]
  node_providers["Model Providers"]
  node_memory[("Shared Memory")]
  node_personal_intelligence["Personal Intelligence<br/>[engine.py]"]
  node_proactive["Proactive Engine<br/>[engine.py]"]
  node_self_improvement["Self Improvement"]
end

subgraph group_capabilities["Desktop Capabilities"]
  node_tools["Tool Registry<br/>[tools.py]"]
  node_filesystem["Filesystem Service<br/>[service.py]"]
  node_vision["Screen Vision"]
  node_application_intelligence["Application Intelligence"]
end

subgraph group_assurance["Safety and Evidence"]
  node_sandbox["Agent Sandboxing"]
  node_verification["Verification Engine<br/>[engine.py]"]
  node_policy["Security Policy<br/>[policy_engine.py]"]
end

node_user(("User"))

node_user -->|"submits commands"| node_control_center
node_control_center -->|"forwards requests"| node_service_bridge
node_service_bridge -->|"dispatches tasks"| node_orchestrator
node_orchestrator -->|"plans goals"| node_planning
node_orchestrator -->|"delegates subtasks"| node_agents
node_agents -->|"executes within"| node_sandbox
node_orchestrator -->|"executes workflows"| node_workflows
node_workflows -->|"dispatches steps"| node_orchestrator
node_orchestrator -->|"dispatches tools"| node_tools
node_tools -->|"reads and writes"| node_filesystem
node_tools -->|"focuses windows"| node_vision
node_tools -->|"routes interactions"| node_application_intelligence
node_orchestrator -->|"routes model requests"| node_intelligence_gateway
node_intelligence_gateway -->|"selects providers"| node_providers
node_orchestrator -->|"shares context"| node_memory
node_workflows -->|"validates outcomes"| node_verification
node_orchestrator -->|"verifies deliverables"| node_verification
node_orchestrator -->|"publishes lifecycle events"| node_events
node_service_bridge -->|"observes events"| node_events
node_voice -.->|"feeds interaction"| node_service_bridge
node_tools -.->|"checks permissions"| node_policy
node_missions -->|"coordinates subtasks"| node_agents
node_personal_intelligence -.->|"stores personal context"| node_memory
node_proactive -->|"continues missions"| node_missions
node_self_improvement -->|"applies policy"| node_policy

click node_control_center "https://github.com/lokilogesh001/optimus/tree/main/gui/optimus"
click node_service_bridge "https://github.com/lokilogesh001/optimus/blob/main/gui/optimus/service_bridge.py"
click node_voice "https://github.com/lokilogesh001/optimus/tree/main/core/interaction"
click node_orchestrator "https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/orchestrator.py"
click node_events "https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/events.py"
click node_planning "https://github.com/lokilogesh001/optimus/tree/main/core/planning"
click node_missions "https://github.com/lokilogesh001/optimus/blob/main/core/missions/engine.py"
click node_workflows "https://github.com/lokilogesh001/optimus/blob/main/core/workflows/engine.py"
click node_agents "https://github.com/lokilogesh001/optimus/tree/main/core/agents"
click node_sandbox "https://github.com/lokilogesh001/optimus/tree/main/core/sandbox"
click node_tools "https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/tools.py"
click node_filesystem "https://github.com/lokilogesh001/optimus/blob/main/core/filesystem/service.py"
click node_vision "https://github.com/lokilogesh001/optimus/tree/main/core/vision"
click node_application_intelligence "https://github.com/lokilogesh001/optimus/tree/main/core/application_intelligence"
click node_intelligence_gateway "https://github.com/lokilogesh001/optimus/tree/main/core/intelligence"
click node_providers "https://github.com/lokilogesh001/optimus/tree/main/core/intelligence/providers"
click node_memory "https://github.com/lokilogesh001/optimus/tree/main/core/memory"
click node_personal_intelligence "https://github.com/lokilogesh001/optimus/blob/main/core/personal_intelligence/engine.py"
click node_proactive "https://github.com/lokilogesh001/optimus/blob/main/core/proactive/engine.py"
click node_verification "https://github.com/lokilogesh001/optimus/blob/main/core/verification/engine.py"
click node_policy "https://github.com/lokilogesh001/optimus/blob/main/core/security/policy_engine.py"
click node_self_improvement "https://github.com/lokilogesh001/optimus/tree/main/core/self_improvement"

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_control_center,node_service_bridge,node_voice,node_user toneBlue
class node_orchestrator,node_events,node_planning,node_missions,node_workflows,node_agents toneAmber
class node_intelligence_gateway,node_providers,node_memory,node_personal_intelligence,node_proactive,node_self_improvement toneMint
class node_tools,node_filesystem,node_vision,node_application_intelligence toneRose
class node_sandbox,node_verification,node_policy toneIndigo
```

## Components

### Interaction

- [Control Center](https://github.com/lokilogesh001/optimus/tree/main/gui/optimus): `gui/optimus`
- [Service Bridge](https://github.com/lokilogesh001/optimus/blob/main/gui/optimus/service_bridge.py): `gui/optimus/service_bridge.py`
- [Voice Interaction](https://github.com/lokilogesh001/optimus/tree/main/core/interaction): `core/interaction`

### Execution Coordination

- [Central Orchestrator](https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/orchestrator.py): `core/orchestrator/orchestrator.py`
- [Execution Events](https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/events.py): `core/orchestrator/events.py`
- [Adaptive Planning](https://github.com/lokilogesh001/optimus/tree/main/core/planning): `core/planning`
- [Mission Engine](https://github.com/lokilogesh001/optimus/blob/main/core/missions/engine.py): `core/missions/engine.py`
- [Workflow Engine](https://github.com/lokilogesh001/optimus/blob/main/core/workflows/engine.py): `core/workflows/engine.py`
- [Specialized Agents](https://github.com/lokilogesh001/optimus/tree/main/core/agents): `core/agents`

### Intelligence

- [Model Gateway](https://github.com/lokilogesh001/optimus/tree/main/core/intelligence): `core/intelligence`
- [Model Providers](https://github.com/lokilogesh001/optimus/tree/main/core/intelligence/providers): `core/intelligence/providers`
- [Shared Memory](https://github.com/lokilogesh001/optimus/tree/main/core/memory): `core/memory`
- [Personal Intelligence](https://github.com/lokilogesh001/optimus/blob/main/core/personal_intelligence/engine.py): `core/personal_intelligence/engine.py`
- [Proactive Engine](https://github.com/lokilogesh001/optimus/blob/main/core/proactive/engine.py): `core/proactive/engine.py`
- [Self Improvement](https://github.com/lokilogesh001/optimus/tree/main/core/self_improvement): `core/self_improvement`

### Desktop Capabilities

- [Tool Registry](https://github.com/lokilogesh001/optimus/blob/main/core/orchestrator/tools.py): `core/orchestrator/tools.py`
- [Filesystem Service](https://github.com/lokilogesh001/optimus/blob/main/core/filesystem/service.py): `core/filesystem/service.py`
- [Screen Vision](https://github.com/lokilogesh001/optimus/tree/main/core/vision): `core/vision`
- [Application Intelligence](https://github.com/lokilogesh001/optimus/tree/main/core/application_intelligence): `core/application_intelligence`

### Safety and Evidence

- [Agent Sandboxing](https://github.com/lokilogesh001/optimus/tree/main/core/sandbox): `core/sandbox`
- [Verification Engine](https://github.com/lokilogesh001/optimus/blob/main/core/verification/engine.py): `core/verification/engine.py`
- [Security Policy](https://github.com/lokilogesh001/optimus/blob/main/core/security/policy_engine.py): `core/security/policy_engine.py`

### Other components

- **User**

## Connections

- User → Control Center: submits commands
- Control Center → Service Bridge: forwards requests
- Service Bridge → Central Orchestrator: dispatches tasks (evidence: `gui/optimus/service_bridge.py`)
- Central Orchestrator → Adaptive Planning: plans goals
- Central Orchestrator → Specialized Agents: delegates subtasks
- Specialized Agents → Agent Sandboxing: executes within
- Central Orchestrator → Workflow Engine: executes workflows (evidence: `core/workflows/engine.py`)
- Workflow Engine → Central Orchestrator: dispatches steps (evidence: `core/workflows/engine.py`)
- Central Orchestrator → Tool Registry: dispatches tools
- Tool Registry → Filesystem Service: reads and writes (evidence: `core/orchestrator/tools.py`)
- Tool Registry → Screen Vision: focuses windows (evidence: `core/orchestrator/tools.py`)
- Tool Registry → Application Intelligence: routes interactions (evidence: `core/orchestrator/tools.py`)
- Central Orchestrator → Model Gateway: routes model requests
- Model Gateway → Model Providers: selects providers
- Central Orchestrator → Shared Memory: shares context
- Workflow Engine → Verification Engine: validates outcomes (evidence: `core/workflows/engine.py`)
- Central Orchestrator → Verification Engine: verifies deliverables
- Central Orchestrator → Execution Events: publishes lifecycle events
- Service Bridge → Execution Events: observes events (evidence: `gui/optimus/service_bridge.py`)
- Voice Interaction → Service Bridge: feeds interaction (evidence: `gui/optimus/service_bridge.py`)
- Tool Registry → Security Policy: checks permissions (evidence: `core/orchestrator/tools.py`)
- Mission Engine → Specialized Agents: coordinates subtasks (evidence: `core/missions/engine.py`)
- Personal Intelligence → Shared Memory: stores personal context
- Proactive Engine → Mission Engine: continues missions (evidence: `core/proactive/engine.py`)
- Self Improvement → Security Policy: applies policy (evidence: `core/self_improvement/promotion_engine.py`)
