# utkarsh56016/kira-hypragent architecture

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

- Interactive diagram: https://gitdiagram.com/utkarsh56016/kira-hypragent
- Repository: https://github.com/utkarsh56016/kira-hypragent

## Overview

Kira HyprAgent is a local-first Linux desktop assistant. CLI requests travel over a Unix socket to the daemon and then into ContextEngine, which routes deterministic desktop or sysadmin actions, retrieves RAG context, or uses local LLM and optional cloud fallback. Voice input follows a separate wake-word → transcription → context → speech-output loop. The graph preserves the documented dashboard and retrieval capabilities; unsampled subsystem connections are omitted where the excerpts and index do not establish them.

Main entry points: [`src/context/context_engine.py`](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/context_engine.py) (Context engine), [`src/daemon.py`](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/daemon.py) (Socket daemon), [`src/voice/pipeline.py`](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/pipeline.py) (Voice pipeline), [`src/commands/base_plugin.py`](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/base_plugin.py) (Command plugin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Assistant runtime"]
  node_cli["CLI client<br/>[cli.py]"]
  node_daemon["Socket daemon<br/>[daemon.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_context["Context engine<br/>[context_engine.py]"]
  node_router["Intent router<br/>[router.py]"]
  node_state["System state<br/>[state_gatherer.py]"]
  node_sanitizer["Input sanitizer<br/>[sanitizer.py]"]
  node_llm["Ollama client<br/>[llm.py]"]
  node_cloud["Gemini fallback<br/>[cloud_fallback.py]"]
end

subgraph group_commands["Desktop and system commands"]
  node_pluginbase["Command plugin API<br/>[base_plugin.py]"]
  node_desktop["Desktop commands<br/>[dms_plugin.py]"]
  node_hyprland["Hyprland adapter<br/>[hyprctl.py]"]
  node_niri["Niri adapter<br/>[niri_control.py]"]
  node_sysadmin["Sysadmin safety"]
end

subgraph group_voice["Voice interaction"]
  node_voicepipeline["Voice pipeline<br/>[pipeline.py]"]
  node_wake["Wake detection<br/>[openwakeword.py]"]
  node_stt["Speech transcription<br/>[faster_whisper.py]"]
  node_tts["Speech synthesis<br/>[piper.py]"]
  node_outputgate["Wake suppression<br/>[output_gate.py]"]
end

subgraph group_rag["Knowledge retrieval"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_vector["Vector retrieval<br/>[vector.py]"]
  node_parentchild["Hierarchical retrieval<br/>[parent_child.py]"]
  node_graphretriever["Graph retrieval<br/>[graph.py]"]
  node_indexer["RAG indexer<br/>[indexer.py]"]
  node_dashboard["RAG dashboard<br/>[dashboard.py]"]
end

node_user(("User"))
node_ollama["Ollama service"]

node_user -->|"submits request"| node_cli
node_cli -->|"sends socket request"| node_daemon
node_daemon -->|"loads settings"| node_config
node_daemon -->|"dispatches request"| node_context
node_daemon -->|"selects adapter"| node_hyprland
node_daemon -->|"selects adapter"| node_niri
node_daemon -->|"starts pipeline"| node_voicepipeline
node_context -->|"classifies intent"| node_router
node_context -->|"gathers state"| node_state
node_context -->|"sanitizes input"| node_sanitizer
node_context -->|"falls back"| node_cloud
node_context -->|"checks privileged action"| node_sysadmin
node_context -->|"dispatches command"| node_desktop
node_context -->|"retrieves context"| node_hybrid
node_daemon -->|"configures client"| node_llm
node_llm -->|"requests generation"| node_ollama
node_pluginbase -->|"defines interface"| node_desktop
node_pluginbase -->|"defines interface"| node_hyprland
node_pluginbase -->|"defines interface"| node_niri
node_pluginbase -->|"defines interface"| node_sysadmin
node_voicepipeline -->|"starts listener"| node_wake
node_voicepipeline -->|"starts transcriber"| node_stt
node_voicepipeline -->|"starts synthesizer"| node_tts
node_voicepipeline -->|"processes speech"| node_context
node_voicepipeline -->|"marks interaction"| node_outputgate
node_wake -->|"checks suppression"| node_outputgate
node_tts -->|"marks playback"| node_outputgate
node_hybrid -->|"retrieves vectors"| node_vector
node_hybrid -->|"retrieves config"| node_parentchild
node_hybrid -->|"retrieves dependencies"| node_graphretriever
node_indexer -->|"builds chunks"| node_parentchild
node_indexer -->|"indexes vectors"| node_vector
node_indexer -->|"builds graph"| node_graphretriever
node_user -->|"views retrieval"| node_dashboard

click node_cli "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/cli.py"
click node_daemon "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/daemon.py"
click node_config "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/config.py"
click node_context "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/context_engine.py"
click node_router "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/router.py"
click node_state "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/state_gatherer.py"
click node_sanitizer "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/sanitizer.py"
click node_llm "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/llm.py"
click node_cloud "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/cloud_fallback.py"
click node_pluginbase "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/base_plugin.py"
click node_desktop "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/dms_plugin.py"
click node_hyprland "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/hyprland/hyprctl.py"
click node_niri "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/niri/niri_control.py"
click node_sysadmin "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/sys_admin_plugin.py"
click node_voicepipeline "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/pipeline.py"
click node_wake "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/wake/openwakeword.py"
click node_stt "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/stt/faster_whisper.py"
click node_tts "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/tts/piper.py"
click node_outputgate "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/output_gate.py"
click node_hybrid "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/hybrid.py"
click node_vector "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/vector.py"
click node_parentchild "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/parent_child.py"
click node_graphretriever "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/graph.py"
click node_indexer "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/indexer.py"
click node_dashboard "https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/dashboard.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_daemon,node_config,node_context,node_router,node_state,node_sanitizer,node_llm,node_cloud,node_user toneBlue
class node_pluginbase,node_desktop,node_hyprland,node_niri,node_sysadmin toneAmber
class node_voicepipeline,node_wake,node_stt,node_tts,node_outputgate toneMint
class node_hybrid,node_vector,node_parentchild,node_graphretriever,node_indexer,node_dashboard toneRose
class node_ollama toneIndigo
```

## Components

### Assistant runtime

- [CLI client](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/cli.py): `src/cli.py`
- [Socket daemon](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/daemon.py): `src/daemon.py`
- [Configuration](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/config.py): `src/config.py`
- [Context engine](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/context_engine.py): `src/context/context_engine.py`
- [Intent router](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/router.py): `src/context/router.py`
- [System state](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/state_gatherer.py): `src/context/state_gatherer.py`
- [Input sanitizer](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/sanitizer.py): `src/context/sanitizer.py`
- [Ollama client](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/llm.py): `src/llm.py`
- [Gemini fallback](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/context/cloud_fallback.py): `src/context/cloud_fallback.py`

### Desktop and system commands

- [Command plugin API](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/base_plugin.py): `src/commands/base_plugin.py`
- [Desktop commands](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/dms_plugin.py): `src/commands/dms_plugin.py`
- [Hyprland adapter](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/hyprland/hyprctl.py): `src/commands/hyprland/hyprctl.py`
- [Niri adapter](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/niri/niri_control.py): `src/commands/niri/niri_control.py`
- [Sysadmin safety](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/commands/sys_admin_plugin.py): `src/commands/sys_admin_plugin.py`

### Voice interaction

- [Voice pipeline](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/pipeline.py): `src/voice/pipeline.py`
- [Wake detection](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/wake/openwakeword.py): `src/voice/wake/openwakeword.py`
- [Speech transcription](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/stt/faster_whisper.py): `src/voice/stt/faster_whisper.py`
- [Speech synthesis](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/tts/piper.py): `src/voice/tts/piper.py`
- [Wake suppression](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/voice/output_gate.py): `src/voice/output_gate.py`

### Knowledge retrieval

- [Hybrid retrieval](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/hybrid.py): `src/rag/hybrid.py`
- [Vector retrieval](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/vector.py): `src/rag/vector.py`
- [Hierarchical retrieval](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/parent_child.py): `src/rag/parent_child.py`
- [Graph retrieval](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/graph.py): `src/rag/graph.py`
- [RAG indexer](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/indexer.py): `src/rag/indexer.py`
- [RAG dashboard](https://github.com/utkarsh56016/kira-hypragent/blob/main/src/rag/dashboard.py): `src/rag/dashboard.py`

### Other components

- **User**
- **Ollama service**

## Connections

- User → CLI client: submits request (evidence: `README.md`)
- CLI client → Socket daemon: sends socket request (evidence: `README.md`)
- Socket daemon → Configuration: loads settings (evidence: `src/daemon.py`)
- Socket daemon → Context engine: dispatches request (evidence: `src/daemon.py`)
- Socket daemon → Hyprland adapter: selects adapter (evidence: `src/daemon.py`)
- Socket daemon → Niri adapter: selects adapter (evidence: `src/daemon.py`)
- Socket daemon → Voice pipeline: starts pipeline (evidence: `src/daemon.py`)
- Context engine → Intent router: classifies intent (evidence: `src/context/context_engine.py`)
- Context engine → System state: gathers state (evidence: `src/context/context_engine.py`)
- Context engine → Input sanitizer: sanitizes input (evidence: `src/context/context_engine.py`)
- Context engine → Gemini fallback: falls back (evidence: `src/context/context_engine.py`)
- Context engine → Sysadmin safety: checks privileged action (evidence: `src/context/context_engine.py`)
- Context engine → Desktop commands: dispatches command (evidence: `src/context/context_engine.py`)
- Context engine → Hybrid retrieval: retrieves context (evidence: `src/context/context_engine.py`)
- Socket daemon → Ollama client: configures client (evidence: `src/daemon.py`)
- Ollama client → Ollama service: requests generation (evidence: `src/llm.py`)
- Command plugin API → Desktop commands: defines interface (evidence: `src/commands/dms_plugin.py`)
- Command plugin API → Hyprland adapter: defines interface (evidence: `src/commands/hyprland/hyprctl.py`)
- Command plugin API → Niri adapter: defines interface (evidence: `src/commands/niri/niri_control.py`)
- Command plugin API → Sysadmin safety: defines interface (evidence: `src/commands/sys_admin_plugin.py`)
- Voice pipeline → Wake detection: starts listener (evidence: `src/daemon.py`)
- Voice pipeline → Speech transcription: starts transcriber (evidence: `src/daemon.py`)
- Voice pipeline → Speech synthesis: starts synthesizer (evidence: `src/daemon.py`)
- Voice pipeline → Context engine: processes speech (evidence: `src/voice/pipeline.py`)
- Voice pipeline → Wake suppression: marks interaction (evidence: `src/voice/pipeline.py`)
- Wake detection → Wake suppression: checks suppression (evidence: `src/voice/wake/openwakeword.py`)
- Speech synthesis → Wake suppression: marks playback (evidence: `src/voice/tts/piper.py`)
- Hybrid retrieval → Vector retrieval: retrieves vectors (evidence: `src/rag/hybrid.py`)
- Hybrid retrieval → Hierarchical retrieval: retrieves config (evidence: `src/rag/hybrid.py`)
- Hybrid retrieval → Graph retrieval: retrieves dependencies (evidence: `src/rag/hybrid.py`)
- RAG indexer → Hierarchical retrieval: builds chunks (evidence: `src/rag/indexer.py`)
- RAG indexer → Vector retrieval: indexes vectors (evidence: `src/rag/indexer.py`)
- RAG indexer → Graph retrieval: builds graph (evidence: `src/rag/indexer.py`)
- User → RAG dashboard: views retrieval (evidence: `README.md`)
