# vigneshwaran484/jarvis-linux architecture

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

- Interactive diagram: https://gitdiagram.com/vigneshwaran484/jarvis-linux
- Repository: https://github.com/vigneshwaran484/jarvis-linux

## Overview

Jarvis-Linux is a Linux voice assistant: a user wakes it, speaks a request, and the agent transcribes it, reasons through an Ollama ReAct loop, optionally invokes tools or memory, then speaks a response. Its runtime also updates a live HUD and logs errors. The README documents desktop, file, media, system, screenshot, and weather tools; they are grouped by role rather than listed individually. Source excerpts confirm key calls, while some tool details and integration wiring are documented only in the README.

Main entry points: [`agent_v2.py`](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py) (Voice agent), [`memory.py`](https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py) (Memory manager), [`wakeword.py`](https://github.com/vigneshwaran484/jarvis-linux/blob/main/wakeword.py) (Wake detection), [`config.py`](https://github.com/vigneshwaran484/jarvis-linux/blob/main/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice interaction"]
  node_wake["Wake detection<br/>[wakeword.py]"]
  node_stt["Speech recognition<br/>[agent_v2.py]"]
  node_tts["Speech synthesis<br/>[agent_v2.py]"]
end

subgraph group_agent["Agent and tools"]
  node_agent["Voice agent<br/>[agent_v2.py]"]
  node_toolloop["ReAct tool loop<br/>[agent_v2.py]"]
  node_desktop["Desktop and system tools<br/>[agent_v2.py]"]
  node_files["File and capture tools<br/>[agent_v2.py]"]
  node_webweather["Web and weather tools<br/>[agent_v2.py]"]
end

subgraph group_memory["Memory"]
  node_memorymanager["Memory manager<br/>[memory.py]"]
  node_shortmemory[("Conversation memory<br/>[memory.py]")]
  node_longmemory[("Semantic memory<br/>[memory.py]")]
  node_embedder["Embedding backend<br/>[memory.py]"]
end

subgraph group_runtime["Runtime support"]
  node_hud["Arc Reactor HUD<br/>[reactor.py]"]
  node_waybar["Waybar state file<br/>[reactor.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_logging["Rotating logger<br/>[jarvis_log.py]"]
end

node_user(("User"))
node_ollama["Local Ollama"]
node_edgevoice["Edge TTS service"]

node_user -->|"speaks request"| node_agent
node_agent -->|"checks wake word"| node_wake
node_wake -->|"recognizes speech"| node_stt
node_agent -->|"transcribes command"| node_stt
node_agent -->|"runs goal"| node_toolloop
node_toolloop -->|"requests reasoning"| node_ollama
node_toolloop -->|"dispatches tools"| node_desktop
node_toolloop -->|"dispatches tools"| node_files
node_toolloop -->|"dispatches tools"| node_webweather
node_agent -->|"uses memory"| node_memorymanager
node_memorymanager -->|"records exchanges"| node_shortmemory
node_memorymanager -->|"stores and searches"| node_longmemory
node_longmemory -->|"embeds facts"| node_embedder
node_agent -->|"speaks reply"| node_tts
node_tts -->|"synthesizes audio"| node_edgevoice
node_agent -->|"updates state"| node_hud
node_hud -->|"writes state"| node_waybar
node_agent -->|"reads settings"| node_config
node_wake -->|"reads wake settings"| node_config
node_memorymanager -->|"reads memory settings"| node_config
node_agent -->|"logs activity"| node_logging
node_memorymanager -->|"logs memory events"| node_logging

click node_agent "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_wake "https://github.com/vigneshwaran484/jarvis-linux/blob/main/wakeword.py"
click node_stt "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_toolloop "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_desktop "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_files "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_webweather "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_tts "https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py"
click node_memorymanager "https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py"
click node_shortmemory "https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py"
click node_longmemory "https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py"
click node_embedder "https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py"
click node_hud "https://github.com/vigneshwaran484/jarvis-linux/blob/main/reactor.py"
click node_waybar "https://github.com/vigneshwaran484/jarvis-linux/blob/main/reactor.py"
click node_config "https://github.com/vigneshwaran484/jarvis-linux/blob/main/config.py"
click node_logging "https://github.com/vigneshwaran484/jarvis-linux/blob/main/jarvis_log.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_wake,node_stt,node_tts,node_user toneBlue
class node_agent,node_toolloop,node_desktop,node_files,node_webweather toneAmber
class node_memorymanager,node_shortmemory,node_longmemory,node_embedder toneMint
class node_hud,node_waybar,node_config,node_logging toneRose
class node_ollama,node_edgevoice toneIndigo
```

## Components

### Voice interaction

- [Wake detection](https://github.com/vigneshwaran484/jarvis-linux/blob/main/wakeword.py): `wakeword.py`
- [Speech recognition](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`
- [Speech synthesis](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`

### Agent and tools

- [Voice agent](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`
- [ReAct tool loop](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`
- [Desktop and system tools](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`
- [File and capture tools](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`
- [Web and weather tools](https://github.com/vigneshwaran484/jarvis-linux/blob/main/agent_v2.py): `agent_v2.py`

### Memory

- [Memory manager](https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py): `memory.py`
- [Conversation memory](https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py): `memory.py`
- [Semantic memory](https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py): `memory.py`
- [Embedding backend](https://github.com/vigneshwaran484/jarvis-linux/blob/main/memory.py): `memory.py`

### Runtime support

- [Arc Reactor HUD](https://github.com/vigneshwaran484/jarvis-linux/blob/main/reactor.py): `reactor.py`
- [Waybar state file](https://github.com/vigneshwaran484/jarvis-linux/blob/main/reactor.py): `reactor.py`
- [Configuration](https://github.com/vigneshwaran484/jarvis-linux/blob/main/config.py): `config.py`
- [Rotating logger](https://github.com/vigneshwaran484/jarvis-linux/blob/main/jarvis_log.py): `jarvis_log.py`

### Other components

- **User**
- **Local Ollama**
- **Edge TTS service**

## Connections

- User → Voice agent: speaks request (evidence: `README.md`)
- Voice agent → Wake detection: checks wake word (evidence: `README.md`)
- Wake detection → Speech recognition: recognizes speech (evidence: `wakeword.py`)
- Voice agent → Speech recognition: transcribes command (evidence: `agent_v2.py`)
- Voice agent → ReAct tool loop: runs goal (evidence: `README.md`)
- ReAct tool loop → Local Ollama: requests reasoning (evidence: `agent_v2.py`)
- ReAct tool loop → Desktop and system tools: dispatches tools (evidence: `README.md`)
- ReAct tool loop → File and capture tools: dispatches tools (evidence: `README.md`)
- ReAct tool loop → Web and weather tools: dispatches tools (evidence: `README.md`)
- Voice agent → Memory manager: uses memory (evidence: `agent_v2.py`)
- Memory manager → Conversation memory: records exchanges (evidence: `memory.py`)
- Memory manager → Semantic memory: stores and searches (evidence: `memory.py`)
- Semantic memory → Embedding backend: embeds facts (evidence: `memory.py`)
- Voice agent → Speech synthesis: speaks reply (evidence: `README.md`)
- Speech synthesis → Edge TTS service: synthesizes audio (evidence: `agent_v2.py`)
- Voice agent → Arc Reactor HUD: updates state (evidence: `README.md`)
- Arc Reactor HUD → Waybar state file: writes state (evidence: `reactor.py`)
- Voice agent → Configuration: reads settings (evidence: `agent_v2.py`)
- Wake detection → Configuration: reads wake settings (evidence: `wakeword.py`)
- Memory manager → Configuration: reads memory settings (evidence: `memory.py`)
- Voice agent → Rotating logger: logs activity (evidence: `README.md`)
- Memory manager → Rotating logger: logs memory events (evidence: `memory.py`)
