# vincenzo-afk/iris architecture

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

- Interactive diagram: https://gitdiagram.com/vincenzo-afk/iris
- Repository: https://github.com/vincenzo-afk/iris

## Overview

IRIS is a local desktop assistant: users select a mode, then receive screen descriptions, contextual chat, hover explanations, bounded computer-use tasks, or voice-driven responses and actions. The graph preserves those distinct modes and the agent’s memory, web, task, and desktop-action capabilities. Several links are documented in the README or visible in indexed imports; unsampled implementations are represented only at their supported directory or module paths.

Main entry points: [`core/agent.py`](https://github.com/vincenzo-afk/iris/blob/main/core/agent.py) (Task agent), [`main.py`](https://github.com/vincenzo-afk/iris/blob/main/main.py) (Mode selector), [`core/vision.py`](https://github.com/vincenzo-afk/iris/blob/main/core/vision.py) (Screen vision), [`core/voice.py`](https://github.com/vincenzo-afk/iris/blob/main/core/voice.py) (Voice listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interaction modes"]
  node_main["Mode selector<br/>[main.py]"]
  node_watch["Screen watch<br/>[vision.py]"]
  node_chat["Contextual chat<br/>[agent.py]"]
  node_teach["Teach mode<br/>[teach_mode.py]"]
  node_voice["Voice listener<br/>[voice.py]"]
end

subgraph group_understanding["Screen understanding"]
  node_vision["Screen vision<br/>[vision.py]"]
  node_screen_tools["Screen tools<br/>[screen_tools.py]"]
end

subgraph group_agent["Agent and memory"]
  node_agent["Task agent<br/>[agent.py]"]
  node_memory["Assistant memory<br/>[memory.py]"]
  node_tasks[("Task list<br/>[task_tools.py]")]
  node_web["Web research<br/>[web_tools.py]"]
end

subgraph group_desktop["Desktop capabilities"]
  node_automation["Input automation<br/>[automation.py]"]
  node_input_tools["Input tools<br/>[input_tools.py]"]
  node_system_tools["System tools<br/>[system_tools.py]"]
  node_overlay["Cursor overlay<br/>[cursor_widget.py]"]
end

subgraph group_settings["Runtime configuration"]
  node_config["Runtime settings<br/>[config.py]"]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}
node_mem0[("Mem0 storage")]
node_desktop_os(("Desktop session"))
node_audio(("Audio devices"))

node_user -->|"selects mode"| node_main
node_main -->|"starts watch"| node_watch
node_main -->|"routes chat"| node_chat
node_main -->|"starts teaching"| node_teach
node_main -->|"runs task"| node_agent
node_main -->|"starts listening"| node_voice
node_watch -->|"analyzes frames"| node_vision
node_teach -->|"analyzes hover"| node_vision
node_teach -->|"shows explanation"| node_overlay
node_voice -->|"delivers commands"| node_main
node_voice -->|"records and speaks"| node_audio
node_chat -->|"answers prompts"| node_gemini
node_vision -->|"describes screen"| node_gemini
node_agent -->|"requests tool calls"| node_gemini
node_agent -->|"loads context"| node_memory
node_memory -->|"stores memories"| node_mem0
node_agent -->|"observes and verifies"| node_vision
node_agent -->|"dispatches actions"| node_automation
node_agent -->|"reads task list"| node_tasks
node_agent -->|"opens applications"| node_system_tools
node_agent -->|"uses web tools"| node_web
node_automation -->|"controls input"| node_desktop_os
node_system_tools -->|"operates system"| node_desktop_os
node_input_tools -->|"delegates input"| node_automation
node_screen_tools -->|"uses capture"| node_vision
node_main -->|"uses settings"| node_config
node_agent -->|"uses settings"| node_config
node_vision -->|"uses settings"| node_config
node_voice -->|"uses settings"| node_config

click node_main "https://github.com/vincenzo-afk/iris/blob/main/main.py"
click node_watch "https://github.com/vincenzo-afk/iris/blob/main/core/vision.py"
click node_chat "https://github.com/vincenzo-afk/iris/blob/main/core/agent.py"
click node_teach "https://github.com/vincenzo-afk/iris/blob/main/overlay/teach_mode.py"
click node_voice "https://github.com/vincenzo-afk/iris/blob/main/core/voice.py"
click node_vision "https://github.com/vincenzo-afk/iris/blob/main/core/vision.py"
click node_screen_tools "https://github.com/vincenzo-afk/iris/blob/main/tools/screen_tools.py"
click node_agent "https://github.com/vincenzo-afk/iris/blob/main/core/agent.py"
click node_memory "https://github.com/vincenzo-afk/iris/blob/main/core/memory.py"
click node_tasks "https://github.com/vincenzo-afk/iris/blob/main/tools/task_tools.py"
click node_web "https://github.com/vincenzo-afk/iris/blob/main/tools/web_tools.py"
click node_automation "https://github.com/vincenzo-afk/iris/blob/main/core/automation.py"
click node_input_tools "https://github.com/vincenzo-afk/iris/blob/main/tools/input_tools.py"
click node_system_tools "https://github.com/vincenzo-afk/iris/blob/main/tools/system_tools.py"
click node_overlay "https://github.com/vincenzo-afk/iris/blob/main/overlay/cursor_widget.py"
click node_config "https://github.com/vincenzo-afk/iris/blob/main/config.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,node_watch,node_chat,node_teach,node_voice,node_user toneBlue
class node_vision,node_screen_tools,node_mem0 toneAmber
class node_agent,node_memory,node_tasks,node_web toneMint
class node_automation,node_input_tools,node_system_tools,node_overlay toneRose
class node_config,node_gemini,node_desktop_os,node_audio toneIndigo
```

## Components

### Interaction modes

- [Mode selector](https://github.com/vincenzo-afk/iris/blob/main/main.py): `main.py`
- [Screen watch](https://github.com/vincenzo-afk/iris/blob/main/core/vision.py): `core/vision.py`
- [Contextual chat](https://github.com/vincenzo-afk/iris/blob/main/core/agent.py): `core/agent.py`
- [Teach mode](https://github.com/vincenzo-afk/iris/blob/main/overlay/teach_mode.py): `overlay/teach_mode.py`
- [Voice listener](https://github.com/vincenzo-afk/iris/blob/main/core/voice.py): `core/voice.py`

### Screen understanding

- [Screen vision](https://github.com/vincenzo-afk/iris/blob/main/core/vision.py): `core/vision.py`
- [Screen tools](https://github.com/vincenzo-afk/iris/blob/main/tools/screen_tools.py): `tools/screen_tools.py`

### Agent and memory

- [Task agent](https://github.com/vincenzo-afk/iris/blob/main/core/agent.py): `core/agent.py`
- [Assistant memory](https://github.com/vincenzo-afk/iris/blob/main/core/memory.py): `core/memory.py`
- [Task list](https://github.com/vincenzo-afk/iris/blob/main/tools/task_tools.py): `tools/task_tools.py`
- [Web research](https://github.com/vincenzo-afk/iris/blob/main/tools/web_tools.py): `tools/web_tools.py`

### Desktop capabilities

- [Input automation](https://github.com/vincenzo-afk/iris/blob/main/core/automation.py): `core/automation.py`
- [Input tools](https://github.com/vincenzo-afk/iris/blob/main/tools/input_tools.py): `tools/input_tools.py`
- [System tools](https://github.com/vincenzo-afk/iris/blob/main/tools/system_tools.py): `tools/system_tools.py`
- [Cursor overlay](https://github.com/vincenzo-afk/iris/blob/main/overlay/cursor_widget.py): `overlay/cursor_widget.py`

### Runtime configuration

- [Runtime settings](https://github.com/vincenzo-afk/iris/blob/main/config.py): `config.py`

### Other components

- **User**
- **Google Gemini**
- **Mem0 storage**
- **Desktop session**
- **Audio devices**

## Connections

- User → Mode selector: selects mode (evidence: `README.md`)
- Mode selector → Screen watch: starts watch (evidence: `main.py`)
- Mode selector → Contextual chat: routes chat (evidence: `main.py`)
- Mode selector → Teach mode: starts teaching (evidence: `main.py`)
- Mode selector → Task agent: runs task (evidence: `main.py`)
- Mode selector → Voice listener: starts listening (evidence: `main.py`)
- Screen watch → Screen vision: analyzes frames (evidence: `README.md`)
- Teach mode → Screen vision: analyzes hover (evidence: `overlay/teach_mode.py`)
- Teach mode → Cursor overlay: shows explanation (evidence: `overlay/teach_mode.py`)
- Voice listener → Mode selector: delivers commands (evidence: `main.py`)
- Voice listener → Audio devices: records and speaks (evidence: `README.md`)
- Contextual chat → Google Gemini: answers prompts (evidence: `README.md`)
- Screen vision → Google Gemini: describes screen (evidence: `README.md`)
- Task agent → Google Gemini: requests tool calls (evidence: `README.md`)
- Task agent → Assistant memory: loads context (evidence: `core/agent.py`)
- Assistant memory → Mem0 storage: stores memories (evidence: `README.md`)
- Task agent → Screen vision: observes and verifies (evidence: `core/agent.py`)
- Task agent → Input automation: dispatches actions (evidence: `core/agent.py`)
- Task agent → Task list: reads task list (evidence: `core/agent.py`)
- Task agent → System tools: opens applications (evidence: `core/agent.py`)
- Task agent → Web research: uses web tools (evidence: `core/agent.py`)
- Input automation → Desktop session: controls input (evidence: `README.md`)
- System tools → Desktop session: operates system (evidence: `tools/system_tools.py`)
- Input tools → Input automation: delegates input (evidence: `tools/input_tools.py`)
- Screen tools → Screen vision: uses capture (evidence: `tools/screen_tools.py`)
- Mode selector → Runtime settings: uses settings (evidence: `main.py`)
- Task agent → Runtime settings: uses settings (evidence: `core/agent.py`)
- Screen vision → Runtime settings: uses settings (evidence: `core/vision.py`)
- Voice listener → Runtime settings: uses settings (evidence: `core/voice.py`)