# tahsin2155/handoff architecture

> Architecture diagram of the GitHub repository tahsin2155/handoff, 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/tahsin2155/handoff
- Repository: https://github.com/tahsin2155/handoff

## Overview

Handoff is a desktop-operating AI agent. A user enters a task through a dialog; the main loop sends the task and a screenshot to Gemini, dispatches returned actions through a safety gate to desktop controls, then sends a fresh screenshot and feedback for the next turn. The loop also supports user hand-back, configurable model settings, and per-run conversation logs. The graph follows the documented workflow and sampled calls; unsampled loop details are not inferred beyond README statements.

Main entry points: [`main.py`](https://github.com/tahsin2155/handoff/blob/main/main.py) (Main Loop), [`executions/hands.py`](https://github.com/tahsin2155/handoff/blob/main/executions/hands.py) (Mouse and Keyboard), [`executions/dialogs.py`](https://github.com/tahsin2155/handoff/blob/main/executions/dialogs.py) (Dialogs), [`executions/tools.py`](https://github.com/tahsin2155/handoff/blob/main/executions/tools.py) (Tool Definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_dialogs["Dialogs<br/>[dialogs.py]"]
end

subgraph group_orchestration["Run Orchestration"]
  node_runner["Main Loop<br/>[main.py]"]
  node_settings["Model Settings<br/>[config.py]"]
  node_history[("Run Logs")]
  node_dispatch["Action Dispatch<br/>[main.py]"]
end

subgraph group_model["Model Guidance"]
  node_prompt["System Instructions<br/>[prompts.py]"]
  node_tools["Tool Definitions<br/>[tools.py]"]
end

subgraph group_execution["Desktop Execution"]
  node_vision["Screen Capture<br/>[vision.py]"]
  node_hands["Mouse and Keyboard<br/>[hands.py]"]
  node_results["Action Results<br/>[results.py]"]
end

node_user(("User"))
node_gemini{{"Gemini Interactions API"}}
node_desktop{{"Desktop"}}

node_user -->|"enters task"| node_dialogs
node_dialogs -->|"provides task"| node_runner
node_runner -->|"reads settings"| node_settings
node_runner -->|"captures screen"| node_vision
node_runner -->|"sets instructions"| node_prompt
node_runner -->|"sends tools"| node_tools
node_runner -->|"sends request"| node_gemini
node_gemini -->|"returns steps"| node_runner
node_runner -->|"runs turn"| node_dispatch
node_dispatch -->|"calls actions"| node_hands
node_hands -->|"controls screen"| node_desktop
node_hands -->|"requests approval"| node_dialogs
node_dispatch -->|"calls hand-back"| node_tools
node_tools -->|"asks for reply"| node_dialogs
node_runner -->|"checks outcomes"| node_results
node_hands -->|"returns outcomes"| node_results
node_runner -->|"writes logs"| node_history

click node_dialogs "https://github.com/tahsin2155/handoff/blob/main/executions/dialogs.py"
click node_runner "https://github.com/tahsin2155/handoff/blob/main/main.py"
click node_settings "https://github.com/tahsin2155/handoff/blob/main/config.py"
click node_history "https://github.com/tahsin2155/handoff/tree/main/convo_history"
click node_prompt "https://github.com/tahsin2155/handoff/blob/main/executions/prompts.py"
click node_tools "https://github.com/tahsin2155/handoff/blob/main/executions/tools.py"
click node_vision "https://github.com/tahsin2155/handoff/blob/main/executions/vision.py"
click node_dispatch "https://github.com/tahsin2155/handoff/blob/main/main.py"
click node_hands "https://github.com/tahsin2155/handoff/blob/main/executions/hands.py"
click node_results "https://github.com/tahsin2155/handoff/blob/main/executions/results.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_dialogs,node_user toneBlue
class node_runner,node_settings,node_history,node_dispatch toneAmber
class node_prompt,node_tools,node_gemini toneMint
class node_vision,node_hands,node_results toneRose
class node_desktop toneIndigo
```

## Components

### User Interaction

- [Dialogs](https://github.com/tahsin2155/handoff/blob/main/executions/dialogs.py): `executions/dialogs.py`

### Run Orchestration

- [Main Loop](https://github.com/tahsin2155/handoff/blob/main/main.py): `main.py`
- [Model Settings](https://github.com/tahsin2155/handoff/blob/main/config.py): `config.py`
- [Run Logs](https://github.com/tahsin2155/handoff/tree/main/convo_history): `convo_history`
- [Action Dispatch](https://github.com/tahsin2155/handoff/blob/main/main.py): `main.py`

### Model Guidance

- [System Instructions](https://github.com/tahsin2155/handoff/blob/main/executions/prompts.py): `executions/prompts.py`
- [Tool Definitions](https://github.com/tahsin2155/handoff/blob/main/executions/tools.py): `executions/tools.py`

### Desktop Execution

- [Screen Capture](https://github.com/tahsin2155/handoff/blob/main/executions/vision.py): `executions/vision.py`
- [Mouse and Keyboard](https://github.com/tahsin2155/handoff/blob/main/executions/hands.py): `executions/hands.py`
- [Action Results](https://github.com/tahsin2155/handoff/blob/main/executions/results.py): `executions/results.py`

### Other components

- **User**
- **Gemini Interactions API**
- **Desktop**

## Connections

- User → Dialogs: enters task (evidence: `README.md`)
- Dialogs → Main Loop: provides task (evidence: `main.py`)
- Main Loop → Model Settings: reads settings (evidence: `main.py`)
- Main Loop → Screen Capture: captures screen (evidence: `README.md`)
- Main Loop → System Instructions: sets instructions (evidence: `main.py`)
- Main Loop → Tool Definitions: sends tools (evidence: `main.py`)
- Main Loop → Gemini Interactions API: sends request (evidence: `main.py`)
- Gemini Interactions API → Main Loop: returns steps (evidence: `README.md`)
- Main Loop → Action Dispatch: runs turn (evidence: `main.py`)
- Action Dispatch → Mouse and Keyboard: calls actions (evidence: `main.py`)
- Mouse and Keyboard → Desktop: controls screen (evidence: `executions/hands.py`)
- Mouse and Keyboard → Dialogs: requests approval (evidence: `executions/hands.py`)
- Action Dispatch → Tool Definitions: calls hand-back (evidence: `main.py`)
- Tool Definitions → Dialogs: asks for reply (evidence: `executions/tools.py`)
- Main Loop → Action Results: checks outcomes (evidence: `main.py`)
- Mouse and Keyboard → Action Results: returns outcomes (evidence: `executions/hands.py`)
- Main Loop → Run Logs: writes logs (evidence: `README.md`)