# ayushman-311214/aetheros architecture

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

- Interactive diagram: https://gitdiagram.com/ayushman-311214/aetheros
- Repository: https://github.com/ayushman-311214/aetheros

## Overview

AetherOS is a desktop-oriented AI assistant runtime: users can interact through a command-line interface or voice, while agent and LLM components support tool-based work across desktop, browser, and vision capabilities. The desktop automation engine runs workflows through the tool execution layer and verifies results; desktop services also expose process, window, and application operations. The tree documents HUD, observability, and event subsystems as additional product capabilities. No README was provided, and several connections are shown only by source-index references, so the graph avoids inferring a complete end-to-end runtime sequence.

Main entry points: [`src/aetheros/agents/agent.py`](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/agent.py) (Agent runtime), [`src/aetheros/desktop/automation/engine.py`](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/automation/engine.py) (Automation engine), [`src/aetheros/bootstrap/bootstrapper.py`](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/bootstrap/bootstrapper.py) (Bootstrapper), [`src/aetheros/cli/main.py`](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/cli/main.py) (CLI runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI runtime<br/>[main.py]"]
  node_voice["Voice pipeline<br/>[pipeline.py]"]
  node_hud["HUD service<br/>[service.py]"]
end

subgraph group_reasoning["Agent reasoning"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_planner["Agent planner<br/>[planner.py]"]
  node_policy["Policy engine<br/>[engine.py]"]
  node_llm["LLM engine<br/>[engine.py]"]
end

subgraph group_execution["Tool execution"]
  node_automation["Automation engine<br/>[engine.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
end

subgraph group_desktop["Desktop capabilities"]
  node_browser["Browser service<br/>[controller.py]"]
  node_application["Application service<br/>[controller.py]"]
  node_process["Process service<br/>[controller.py]"]
  node_window["Window service<br/>[controller.py]"]
  node_screen["Screen service<br/>[controller.py]"]
  node_vision["Vision service<br/>[controller.py]"]
end

subgraph group_services["Runtime services"]
  node_bootstrap["Bootstrapper<br/>[bootstrapper.py]"]
  node_container["Service container<br/>[container.py]"]
  node_events["Event bus<br/>[event_bus.py]"]
  node_observability["Observability pipeline<br/>[pipeline.py]"]
end

node_user(("User"))

node_user -.->|"issues commands"| node_cli
node_cli -->|"uses events"| node_events
node_cli -->|"uses HUD"| node_hud
node_voice -->|"publishes events"| node_events
node_voice -->|"emits traces"| node_observability
node_agent -.->|"plans tasks"| node_planner
node_agent -.->|"checks policy"| node_policy
node_agent -.->|"requests reasoning"| node_llm
node_automation -->|"executes steps"| node_executor
node_automation -->|"checks tools"| node_registry
node_automation -.->|"verifies outcomes"| node_vision
node_bootstrap -->|"configures services"| node_container
node_bootstrap -->|"discovers tools"| node_registry
node_bootstrap -->|"configures events"| node_events
node_application -->|"manages processes"| node_process
node_application -->|"resolves windows"| node_window
node_vision -.->|"analyzes captures"| node_screen

click node_cli "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/cli/main.py"
click node_voice "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/voice/pipeline.py"
click node_hud "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/hud/service.py"
click node_agent "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/agent.py"
click node_planner "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/planner/planner.py"
click node_policy "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/policy/engine.py"
click node_llm "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/llm/engine.py"
click node_automation "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/automation/engine.py"
click node_executor "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/tools/executor.py"
click node_registry "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/tools/registry.py"
click node_bootstrap "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/bootstrap/bootstrapper.py"
click node_container "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/core/container/container.py"
click node_events "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/runtime/events/event_bus.py"
click node_observability "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/core/observability/pipeline.py"
click node_browser "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/browser/controller.py"
click node_application "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/application/controller.py"
click node_process "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/process/controller.py"
click node_window "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/window/controller.py"
click node_screen "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/screen/controller.py"
click node_vision "https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/vision/controller.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_cli,node_voice,node_hud,node_user toneBlue
class node_agent,node_planner,node_policy,node_llm toneAmber
class node_automation,node_executor,node_registry toneMint
class node_browser,node_application,node_process,node_window,node_screen,node_vision toneRose
class node_bootstrap,node_container,node_events,node_observability toneIndigo
```

## Components

### User interaction

- [CLI runtime](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/cli/main.py): `src/aetheros/cli/main.py`
- [Voice pipeline](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/voice/pipeline.py): `src/aetheros/voice/pipeline.py`
- [HUD service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/hud/service.py): `src/aetheros/hud/service.py`

### Agent reasoning

- [Agent runtime](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/agent.py): `src/aetheros/agents/agent.py`
- [Agent planner](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/planner/planner.py): `src/aetheros/agents/planner/planner.py`
- [Policy engine](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/agents/policy/engine.py): `src/aetheros/agents/policy/engine.py`
- [LLM engine](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/llm/engine.py): `src/aetheros/llm/engine.py`

### Tool execution

- [Automation engine](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/automation/engine.py): `src/aetheros/desktop/automation/engine.py`
- [Tool executor](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/tools/executor.py): `src/aetheros/tools/executor.py`
- [Tool registry](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/tools/registry.py): `src/aetheros/tools/registry.py`

### Desktop capabilities

- [Browser service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/browser/controller.py): `src/aetheros/browser/controller.py`
- [Application service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/application/controller.py): `src/aetheros/desktop/application/controller.py`
- [Process service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/process/controller.py): `src/aetheros/desktop/process/controller.py`
- [Window service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/window/controller.py): `src/aetheros/desktop/window/controller.py`
- [Screen service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/desktop/screen/controller.py): `src/aetheros/desktop/screen/controller.py`
- [Vision service](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/vision/controller.py): `src/aetheros/vision/controller.py`

### Runtime services

- [Bootstrapper](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/bootstrap/bootstrapper.py): `src/aetheros/bootstrap/bootstrapper.py`
- [Service container](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/core/container/container.py): `src/aetheros/core/container/container.py`
- [Event bus](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/runtime/events/event_bus.py): `src/aetheros/runtime/events/event_bus.py`
- [Observability pipeline](https://github.com/ayushman-311214/aetheros/blob/development/src/aetheros/core/observability/pipeline.py): `src/aetheros/core/observability/pipeline.py`

### Other components

- **User**

## Connections

- User → CLI runtime: issues commands
- CLI runtime → Event bus: uses events (evidence: `src/aetheros/cli/main.py`)
- CLI runtime → HUD service: uses HUD (evidence: `src/aetheros/cli/main.py`)
- Voice pipeline → Event bus: publishes events (evidence: `src/aetheros/voice/pipeline.py`)
- Voice pipeline → Observability pipeline: emits traces (evidence: `src/aetheros/voice/pipeline.py`)
- Agent runtime → Agent planner: plans tasks
- Agent runtime → Policy engine: checks policy
- Agent runtime → LLM engine: requests reasoning
- Automation engine → Tool executor: executes steps (evidence: `src/aetheros/desktop/automation/engine.py`)
- Automation engine → Tool registry: checks tools (evidence: `src/aetheros/desktop/automation/engine.py`)
- Automation engine → Vision service: verifies outcomes
- Bootstrapper → Service container: configures services (evidence: `src/aetheros/bootstrap/bootstrapper.py`)
- Bootstrapper → Tool registry: discovers tools (evidence: `src/aetheros/bootstrap/bootstrapper.py`)
- Bootstrapper → Event bus: configures events (evidence: `src/aetheros/bootstrap/bootstrapper.py`)
- Application service → Process service: manages processes (evidence: `src/aetheros/desktop/application/controller.py`)
- Application service → Window service: resolves windows (evidence: `src/aetheros/desktop/application/controller.py`)
- Vision service → Screen service: analyzes captures
