# kevalparmar75/optimus-assistant architecture

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

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

## Overview

Optimus is a voice-controlled, Transformers-themed desktop assistant. Its main workflow is voice command → supervisor routing → specialist agent → spoken response; the app also supports browser and screen control, general tools, memory and notes, reminders, and code generation or execution. The README documents several capabilities not visible in sampled implementation, so those links are cited to the README. The source excerpts do not show the complete LangGraph wiring or all reminder and speech behavior.

Main entry points: [`main.py`](https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py) (Command supervisor), [`agents/memory_agent.py`](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py) (Memory agent), [`agents/chat_agent.py`](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/chat_agent.py) (Chat agent), [`agents/reminder_agent.py`](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/reminder_agent.py) (Reminder agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice and HUD"]
  node_main_app["Assistant runtime<br/>[main.py]"]
  node_hud["Character HUD<br/>[hud.py]"]
  node_spoken_response["Spoken response<br/>[main.py]"]
end

subgraph group_routing["Routing and agents"]
  node_supervisor["Command supervisor<br/>[main.py]"]
  node_chat_agent["Chat agent<br/>[chat_agent.py]"]
  node_browser_agent["Browser agent<br/>[browser_agent.py]"]
  node_code_agent["Code agent<br/>[code_agent.py]"]
  node_memory_agent["Memory agent<br/>[memory_agent.py]"]
  node_reminder_agent["Reminder agent<br/>[reminder_agent.py]"]
end

subgraph group_capabilities["Assistant capabilities"]
  node_vision_agent["Vision agent<br/>[vision_agent.py]"]
  node_browser["Browser control<br/>[browser_agent.py]"]
  node_screen_control["Screen capture and actions<br/>[vision_agent.py]"]
  node_code_execution["Code tasks<br/>[code_agent.py]"]
  node_memory_store[("Conversation memory<br/>[memory_agent.py]")]
  node_notes["Notes<br/>[memory_agent.py]"]
  node_reminder_schedule["Reminder scheduling<br/>[reminder_agent.py]"]
end

subgraph group_state_tools["State and tools"]
  node_shared_state["Agent state<br/>[state.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
end

node_user(("Voice user"))
node_external_services["External services"]

node_user -->|"gives command"| node_main_app
node_main_app -->|"routes command"| node_supervisor
node_supervisor -->|"passes state"| node_shared_state
node_supervisor -->|"dispatches to"| node_chat_agent
node_supervisor -->|"dispatches to"| node_browser_agent
node_supervisor -->|"dispatches to"| node_code_agent
node_supervisor -->|"dispatches to"| node_memory_agent
node_supervisor -->|"dispatches to"| node_reminder_agent
node_supervisor -->|"dispatches to"| node_vision_agent
node_main_app -->|"updates display"| node_hud
node_browser_agent -->|"executes actions"| node_browser
node_browser_agent -->|"delegates vision"| node_screen_control
node_vision_agent -->|"captures and acts"| node_screen_control
node_code_agent -->|"calls tools"| node_tool_registry
node_chat_agent -->|"calls tools"| node_tool_registry
node_memory_agent -->|"wires and calls"| node_tool_registry
node_reminder_agent -->|"registers tools"| node_tool_registry
node_memory_agent -->|"stores and recalls"| node_memory_store
node_memory_agent -->|"reads and writes"| node_notes
node_reminder_agent -->|"schedules jobs"| node_reminder_schedule
node_reminder_agent -.->|"notifies user"| node_external_services
node_chat_agent -->|"queries model"| node_external_services
node_code_agent -->|"queries model"| node_external_services
node_vision_agent -->|"queries vision model"| node_external_services
node_main_app -->|"speaks reply"| node_spoken_response
node_main_app -->|"saves conversation"| node_memory_agent
node_chat_agent -.->|"searches web"| node_external_services

click node_main_app "https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py"
click node_hud "https://github.com/kevalparmar75/optimus-assistant/blob/master/ui/hud.py"
click node_supervisor "https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py"
click node_shared_state "https://github.com/kevalparmar75/optimus-assistant/blob/master/state.py"
click node_chat_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/chat_agent.py"
click node_browser_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/browser_agent.py"
click node_code_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/code_agent.py"
click node_memory_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py"
click node_reminder_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/reminder_agent.py"
click node_vision_agent "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/vision_agent.py"
click node_tool_registry "https://github.com/kevalparmar75/optimus-assistant/blob/master/tools/registry.py"
click node_browser "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/browser_agent.py"
click node_screen_control "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/vision_agent.py"
click node_code_execution "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/code_agent.py"
click node_memory_store "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py"
click node_notes "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py"
click node_reminder_schedule "https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/reminder_agent.py"
click node_spoken_response "https://github.com/kevalparmar75/optimus-assistant/blob/master/main.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_main_app,node_hud,node_spoken_response,node_user toneBlue
class node_supervisor,node_chat_agent,node_browser_agent,node_code_agent,node_memory_agent,node_reminder_agent toneAmber
class node_vision_agent,node_browser,node_screen_control,node_code_execution,node_memory_store,node_notes,node_reminder_schedule toneMint
class node_shared_state,node_tool_registry toneRose
class node_external_services toneIndigo
```

## Components

### Voice and HUD

- [Assistant runtime](https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py): `main.py`
- [Character HUD](https://github.com/kevalparmar75/optimus-assistant/blob/master/ui/hud.py): `ui/hud.py`
- [Spoken response](https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py): `main.py`

### Routing and agents

- [Command supervisor](https://github.com/kevalparmar75/optimus-assistant/blob/master/main.py): `main.py`
- [Chat agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/chat_agent.py): `agents/chat_agent.py`
- [Browser agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/browser_agent.py): `agents/browser_agent.py`
- [Code agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/code_agent.py): `agents/code_agent.py`
- [Memory agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py): `agents/memory_agent.py`
- [Reminder agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/reminder_agent.py): `agents/reminder_agent.py`

### Assistant capabilities

- [Vision agent](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/vision_agent.py): `agents/vision_agent.py`
- [Browser control](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/browser_agent.py): `agents/browser_agent.py`
- [Screen capture and actions](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/vision_agent.py): `agents/vision_agent.py`
- [Code tasks](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/code_agent.py): `agents/code_agent.py`
- [Conversation memory](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py): `agents/memory_agent.py`
- [Notes](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/memory_agent.py): `agents/memory_agent.py`
- [Reminder scheduling](https://github.com/kevalparmar75/optimus-assistant/blob/master/agents/reminder_agent.py): `agents/reminder_agent.py`

### State and tools

- [Agent state](https://github.com/kevalparmar75/optimus-assistant/blob/master/state.py): `state.py`
- [Tool registry](https://github.com/kevalparmar75/optimus-assistant/blob/master/tools/registry.py): `tools/registry.py`

### Other components

- **Voice user**
- **External services**

## Connections

- Voice user → Assistant runtime: gives command (evidence: `README.md`)
- Assistant runtime → Command supervisor: routes command (evidence: `README.md`)
- Command supervisor → Agent state: passes state (evidence: `main.py`)
- Command supervisor → Chat agent: dispatches to (evidence: `README.md`)
- Command supervisor → Browser agent: dispatches to (evidence: `README.md`)
- Command supervisor → Code agent: dispatches to (evidence: `README.md`)
- Command supervisor → Memory agent: dispatches to (evidence: `README.md`)
- Command supervisor → Reminder agent: dispatches to (evidence: `README.md`)
- Command supervisor → Vision agent: dispatches to (evidence: `README.md`)
- Assistant runtime → Character HUD: updates display (evidence: `main.py`)
- Browser agent → Browser control: executes actions (evidence: `agents/browser_agent.py`)
- Browser agent → Screen capture and actions: delegates vision (evidence: `agents/browser_agent.py`)
- Vision agent → Screen capture and actions: captures and acts (evidence: `agents/vision_agent.py`)
- Code agent → Tool registry: calls tools (evidence: `agents/code_agent.py`)
- Chat agent → Tool registry: calls tools (evidence: `agents/chat_agent.py`)
- Memory agent → Tool registry: wires and calls (evidence: `agents/memory_agent.py`)
- Reminder agent → Tool registry: registers tools (evidence: `agents/reminder_agent.py`)
- Memory agent → Conversation memory: stores and recalls (evidence: `agents/memory_agent.py`)
- Memory agent → Notes: reads and writes (evidence: `agents/memory_agent.py`)
- Reminder agent → Reminder scheduling: schedules jobs (evidence: `agents/reminder_agent.py`)
- Reminder agent → External services: notifies user (evidence: `README.md`)
- Chat agent → External services: queries model (evidence: `agents/chat_agent.py`)
- Code agent → External services: queries model (evidence: `agents/code_agent.py`)
- Vision agent → External services: queries vision model (evidence: `agents/vision_agent.py`)
- Assistant runtime → Spoken response: speaks reply (evidence: `README.md`)
- Assistant runtime → Memory agent: saves conversation (evidence: `README.md`)
- Chat agent → External services: searches web (evidence: `README.md`)
