# nikeshsundar/argus architecture

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

- Interactive diagram: https://gitdiagram.com/nikeshsundar/argus
- Repository: https://github.com/nikeshsundar/argus

## Overview

Argus is a Windows desktop assistant: users invoke it from a hotkey or overlay, ask about the current screen, or delegate desktop work. The main process coordinates providers, screen capture, action execution, approvals and persistence; renderer and preload code provide the interaction surface. Documented branches include voice, screen memory, saved workflows, Teach Mode, SOPs and model selection. Several domain modules are indexed but unsampled, so their internal call paths are not inferred.

Main entry points: [`src/main/index.ts`](https://github.com/nikeshsundar/argus/blob/main/src/main/index.ts) (Main process), [`src/main/agentLoop.ts`](https://github.com/nikeshsundar/argus/blob/main/src/main/agentLoop.ts) (Agent loop), [`src/renderer/src/main.ts`](https://github.com/nikeshsundar/argus/blob/main/src/renderer/src/main.ts) (Overlay UI), [`src/main/overlayWindow.ts`](https://github.com/nikeshsundar/argus/blob/main/src/main/overlayWindow.ts) (Overlay window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interaction"]
  node_hotkey["Hotkey<br/>[hotkey.ts]"]
  node_main["Main process<br/>[index.ts]"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_renderer["Overlay UI<br/>[main.ts]"]
  node_overlay["Overlay window<br/>[overlayWindow.ts]"]
  node_voice["Voice input<br/>[voice.ts]"]
end

subgraph group_ai["AI and execution"]
  node_agentloop["Agent loop<br/>[agentLoop.ts]"]
  node_capture["Screen capture<br/>[screenshot.ts]"]
  node_geminiagent["Gemini agent<br/>[geminiAgent.ts]"]
  node_providers["Talk providers"]
  node_geminicli["Gemini client<br/>[geminiClient.ts]"]
  node_input["Desktop actions<br/>[inputSim.ts]"]
end

subgraph group_domains["Assistant capabilities"]
  node_memory["Screen memory<br/>[screenMemory.ts]"]
  node_recipes["Recipes and research<br/>[recipes.ts]"]
  node_teach["Teach mode<br/>[teachLoop.ts]"]
  node_sop["SOP runner<br/>[sopRunner.ts]"]
  node_workflow[("Saved workflows<br/>[workflowStore.ts]")]
end

subgraph group_state["State and safeguards"]
  node_settings[("Settings<br/>[settingsStore.ts]")]
  node_history[("Chat history<br/>[history.ts]")]
  node_safety["Action safety<br/>[safety.ts]"]
  node_limits["Agent limits<br/>[limits.ts]"]
  node_geminikeys["Gemini key pool<br/>[geminiKeys.ts]"]
end

node_user(("User"))

node_user -->|"invokes"| node_hotkey
node_hotkey -->|"signals"| node_main
node_main -->|"dispatches"| node_agentloop
node_main -->|"dispatches"| node_sop
node_main -->|"dispatches"| node_recipes
node_main -->|"uses"| node_workflow
node_main -->|"loads"| node_settings
node_main -->|"selects"| node_providers
node_main -.->|"persists"| node_history
node_main -->|"controls"| node_overlay
node_overlay -->|"loads"| node_preload
node_preload -->|"bridges"| node_renderer
node_renderer -->|"uses"| node_voice
node_agentloop -->|"captures"| node_capture
node_agentloop -->|"creates session"| node_geminiagent
node_agentloop -->|"executes actions"| node_input
node_agentloop -->|"reports progress"| node_overlay
node_agentloop -->|"loads limits"| node_settings
node_agentloop -->|"checks risk"| node_safety
node_agentloop -->|"applies constraints"| node_limits
node_providers -->|"uses"| node_geminicli
node_geminicli -->|"takes keys"| node_geminikeys
node_memory -.->|"shown in Talk Mode"| node_renderer
node_recipes -->|"uses"| node_geminicli
node_teach -.->|"reports steps"| node_overlay
node_sop -->|"runs screen steps"| node_agentloop
node_workflow -.->|"offered to user"| node_renderer

click node_hotkey "https://github.com/nikeshsundar/argus/blob/main/src/main/hotkey.ts"
click node_main "https://github.com/nikeshsundar/argus/blob/main/src/main/index.ts"
click node_preload "https://github.com/nikeshsundar/argus/blob/main/src/preload/index.ts"
click node_renderer "https://github.com/nikeshsundar/argus/blob/main/src/renderer/src/main.ts"
click node_overlay "https://github.com/nikeshsundar/argus/blob/main/src/main/overlayWindow.ts"
click node_voice "https://github.com/nikeshsundar/argus/blob/main/src/renderer/src/voice.ts"
click node_agentloop "https://github.com/nikeshsundar/argus/blob/main/src/main/agentLoop.ts"
click node_capture "https://github.com/nikeshsundar/argus/blob/main/src/main/screenshot.ts"
click node_geminiagent "https://github.com/nikeshsundar/argus/blob/main/src/main/providers/geminiAgent.ts"
click node_providers "https://github.com/nikeshsundar/argus/tree/main/src/main/providers"
click node_geminicli "https://github.com/nikeshsundar/argus/blob/main/src/main/providers/geminiClient.ts"
click node_input "https://github.com/nikeshsundar/argus/blob/main/src/main/inputSim.ts"
click node_memory "https://github.com/nikeshsundar/argus/blob/main/src/main/screenMemory.ts"
click node_recipes "https://github.com/nikeshsundar/argus/blob/main/src/main/recipes.ts"
click node_teach "https://github.com/nikeshsundar/argus/blob/main/src/main/teachLoop.ts"
click node_sop "https://github.com/nikeshsundar/argus/blob/main/src/main/sopRunner.ts"
click node_workflow "https://github.com/nikeshsundar/argus/blob/main/src/main/workflowStore.ts"
click node_settings "https://github.com/nikeshsundar/argus/blob/main/src/main/settingsStore.ts"
click node_history "https://github.com/nikeshsundar/argus/blob/main/src/main/history.ts"
click node_safety "https://github.com/nikeshsundar/argus/blob/main/src/shared/safety.ts"
click node_limits "https://github.com/nikeshsundar/argus/blob/main/src/shared/limits.ts"
click node_geminikeys "https://github.com/nikeshsundar/argus/blob/main/src/main/geminiKeys.ts"

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_hotkey,node_main,node_preload,node_renderer,node_overlay,node_voice,node_user toneBlue
class node_agentloop,node_capture,node_geminiagent,node_providers,node_geminicli,node_input toneAmber
class node_memory,node_recipes,node_teach,node_sop,node_workflow toneMint
class node_settings,node_history,node_safety,node_limits,node_geminikeys toneRose
```

## Components

### Desktop interaction

- [Hotkey](https://github.com/nikeshsundar/argus/blob/main/src/main/hotkey.ts): `src/main/hotkey.ts`
- [Main process](https://github.com/nikeshsundar/argus/blob/main/src/main/index.ts): `src/main/index.ts`
- [Preload bridge](https://github.com/nikeshsundar/argus/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Overlay UI](https://github.com/nikeshsundar/argus/blob/main/src/renderer/src/main.ts): `src/renderer/src/main.ts`
- [Overlay window](https://github.com/nikeshsundar/argus/blob/main/src/main/overlayWindow.ts): `src/main/overlayWindow.ts`
- [Voice input](https://github.com/nikeshsundar/argus/blob/main/src/renderer/src/voice.ts): `src/renderer/src/voice.ts`

### AI and execution

- [Agent loop](https://github.com/nikeshsundar/argus/blob/main/src/main/agentLoop.ts): `src/main/agentLoop.ts`
- [Screen capture](https://github.com/nikeshsundar/argus/blob/main/src/main/screenshot.ts): `src/main/screenshot.ts`
- [Gemini agent](https://github.com/nikeshsundar/argus/blob/main/src/main/providers/geminiAgent.ts): `src/main/providers/geminiAgent.ts`
- [Talk providers](https://github.com/nikeshsundar/argus/tree/main/src/main/providers): `src/main/providers`
- [Gemini client](https://github.com/nikeshsundar/argus/blob/main/src/main/providers/geminiClient.ts): `src/main/providers/geminiClient.ts`
- [Desktop actions](https://github.com/nikeshsundar/argus/blob/main/src/main/inputSim.ts): `src/main/inputSim.ts`

### Assistant capabilities

- [Screen memory](https://github.com/nikeshsundar/argus/blob/main/src/main/screenMemory.ts): `src/main/screenMemory.ts`
- [Recipes and research](https://github.com/nikeshsundar/argus/blob/main/src/main/recipes.ts): `src/main/recipes.ts`
- [Teach mode](https://github.com/nikeshsundar/argus/blob/main/src/main/teachLoop.ts): `src/main/teachLoop.ts`
- [SOP runner](https://github.com/nikeshsundar/argus/blob/main/src/main/sopRunner.ts): `src/main/sopRunner.ts`
- [Saved workflows](https://github.com/nikeshsundar/argus/blob/main/src/main/workflowStore.ts): `src/main/workflowStore.ts`

### State and safeguards

- [Settings](https://github.com/nikeshsundar/argus/blob/main/src/main/settingsStore.ts): `src/main/settingsStore.ts`
- [Chat history](https://github.com/nikeshsundar/argus/blob/main/src/main/history.ts): `src/main/history.ts`
- [Action safety](https://github.com/nikeshsundar/argus/blob/main/src/shared/safety.ts): `src/shared/safety.ts`
- [Agent limits](https://github.com/nikeshsundar/argus/blob/main/src/shared/limits.ts): `src/shared/limits.ts`
- [Gemini key pool](https://github.com/nikeshsundar/argus/blob/main/src/main/geminiKeys.ts): `src/main/geminiKeys.ts`

### Other components

- **User**

## Connections

- User → Hotkey: invokes (evidence: `README.md`)
- Hotkey → Main process: signals (evidence: `src/main/index.ts`)
- Main process → Agent loop: dispatches (evidence: `src/main/index.ts`)
- Main process → SOP runner: dispatches (evidence: `src/main/index.ts`)
- Main process → Recipes and research: dispatches (evidence: `src/main/index.ts`)
- Main process → Saved workflows: uses (evidence: `src/main/index.ts`)
- Main process → Settings: loads (evidence: `src/main/index.ts`)
- Main process → Talk providers: selects (evidence: `src/main/providers/index.ts`)
- Main process → Chat history: persists (evidence: `src/main/index.ts`)
- Main process → Overlay window: controls (evidence: `src/main/overlayWindow.ts`)
- Overlay window → Preload bridge: loads (evidence: `src/main/overlayWindow.ts`)
- Preload bridge → Overlay UI: bridges (evidence: `src/preload/index.ts`)
- Overlay UI → Voice input: uses (evidence: `src/renderer/src/main.ts`)
- Agent loop → Screen capture: captures (evidence: `src/main/agentLoop.ts`)
- Agent loop → Gemini agent: creates session (evidence: `src/main/agentLoop.ts`)
- Agent loop → Desktop actions: executes actions (evidence: `src/main/agentLoop.ts`)
- Agent loop → Overlay window: reports progress (evidence: `src/main/agentLoop.ts`)
- Agent loop → Settings: loads limits (evidence: `src/main/agentLoop.ts`)
- Agent loop → Action safety: checks risk (evidence: `src/main/agentLoop.ts`)
- Agent loop → Agent limits: applies constraints (evidence: `src/main/agentLoop.ts`)
- Talk providers → Gemini client: uses (evidence: `src/main/providers/geminiClient.ts`)
- Gemini client → Gemini key pool: takes keys (evidence: `src/main/providers/geminiClient.ts`)
- Screen memory → Overlay UI: shown in Talk Mode (evidence: `README.md`)
- Recipes and research → Gemini client: uses (evidence: `src/main/recipes.ts`)
- Teach mode → Overlay window: reports steps
- SOP runner → Agent loop: runs screen steps (evidence: `src/main/sopRunner.ts`)
- Saved workflows → Overlay UI: offered to user (evidence: `README.md`)
