# simonschubert/kai architecture

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

- Interactive diagram: https://gitdiagram.com/simonschubert/kai
- Repository: https://github.com/simonschubert/kai

## Overview

Kai is a cross-platform AI assistant centered on a chat loop: the user sends a message, Kai assembles a prompt with persistent memories, calls a configured AI service, executes requested tools, and returns the response while retaining conversation state. Separate capabilities include local inference, generated interactive UI, autonomous heartbeat, skills/MCP, and Android Linux sandboxing. Workflow details follow the README; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatViewModel.kt`](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatViewModel.kt) (Chat workflow), [`composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/HeartbeatManager.kt`](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/HeartbeatManager.kt) (Heartbeat manager), [`composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ToolExecutor.kt`](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ToolExecutor.kt) (Tool executor), [`composeApp/src/androidMain/kotlin/com/inspiredandroid/kai/sandbox/LinuxSandboxManager.kt`](https://github.com/simonschubert/kai/blob/main/composeApp/src/androidMain/kotlin/com/inspiredandroid/kai/sandbox/LinuxSandboxManager.kt) (Linux sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat and AI"]
  node_chatui["Chat interface<br/>[ChatScreen.kt]"]
  node_chatvm["Chat workflow<br/>[ChatViewModel.kt]"]
  node_prompt["Prompt builder"]
  node_services["AI services<br/>[Service.kt]"]
  node_dynamicui["Interactive UI<br/>[KaiUiRenderer.kt]"]
  node_speech["Text to speech<br/>[KaiUiTts.kt]"]
end

subgraph group_state["Memory and settings"]
  node_conversation[("Conversation history")]
  node_memory[("Persistent memory<br/>[MemoryStore.kt]")]
  node_settings[("Assistant settings")]
end

subgraph group_actions["Tools and integrations"]
  node_toolsexec["Tool executor<br/>[ToolExecutor.kt]"]
  node_agenttools["Agent tool set<br/>[AgentToolSet.kt]"]
  node_mcp["MCP servers"]
  node_skills["Skills manager<br/>[SkillManager.kt]"]
  node_notifications["Device notifications"]
end

subgraph group_background["Autonomous features"]
  node_heartbeat["Heartbeat manager"]
  node_scheduler["Task scheduler<br/>[TaskScheduler.kt]"]
end

subgraph group_platform["Local runtimes"]
  node_sandboxui["Sandbox interface"]
  node_sandbox["Linux sandbox"]
  node_localengine["On-device inference"]
end

node_user(("User"))
node_provider{{"AI provider"}}

node_user -->|"sends message"| node_chatui
node_chatui -->|"submits input"| node_chatvm
node_chatvm -->|"builds prompt"| node_prompt
node_chatvm -->|"recalls and stores"| node_memory
node_chatvm -->|"loads and saves"| node_conversation
node_chatvm -->|"selects service"| node_services
node_chatvm -->|"requests completion"| node_provider
node_provider -->|"returns response"| node_chatvm
node_chatvm -->|"dispatches calls"| node_toolsexec
node_toolsexec -->|"runs tools"| node_agenttools
node_agenttools -.->|"uses configured servers"| node_mcp
node_chatvm -->|"renders generated UI"| node_dynamicui
node_chatvm -.->|"uses local inference"| node_localengine
node_chatvm -.->|"reads responses"| node_speech
node_heartbeat -->|"reviews memories"| node_memory
node_heartbeat -->|"reviews pending tasks"| node_scheduler
node_heartbeat -->|"requests self-check"| node_provider
node_heartbeat -->|"surfaces attention"| node_notifications
node_settings -->|"configures assistant"| node_chatvm
node_sandboxui -->|"controls environment"| node_sandbox
node_toolsexec -.->|"runs shell commands"| node_sandbox
node_skills -->|"loads and installs skills"| node_sandbox

click node_chatui "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatScreen.kt"
click node_chatvm "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatViewModel.kt"
click node_prompt "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ChatSystemPromptBuilder.kt"
click node_services "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/Service.kt"
click node_toolsexec "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ToolExecutor.kt"
click node_agenttools "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/AgentToolSet.kt"
click node_mcp "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/mcp/McpServerManager.kt"
click node_conversation "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ConversationStorage.kt"
click node_memory "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/MemoryStore.kt"
click node_settings "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/AppSettingsService.kt"
click node_dynamicui "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiRenderer.kt"
click node_heartbeat "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/HeartbeatManager.kt"
click node_scheduler "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/TaskScheduler.kt"
click node_skills "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/skills/SkillManager.kt"
click node_sandboxui "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/sandbox/SandboxSessionViewModel.kt"
click node_sandbox "https://github.com/simonschubert/kai/blob/main/composeApp/src/androidMain/kotlin/com/inspiredandroid/kai/sandbox/LinuxSandboxManager.kt"
click node_localengine "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/inference/LocalInferenceEngine.kt"
click node_speech "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiTts.kt"
click node_notifications "https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/NotificationTools.kt"

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_chatui,node_chatvm,node_prompt,node_services,node_dynamicui,node_speech,node_user toneBlue
class node_conversation,node_memory,node_settings toneAmber
class node_toolsexec,node_agenttools,node_mcp,node_skills,node_notifications toneMint
class node_heartbeat,node_scheduler toneRose
class node_sandboxui,node_sandbox,node_localengine,node_provider toneIndigo
```

## Components

### Chat and AI

- [Chat interface](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatScreen.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatScreen.kt`
- [Chat workflow](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatViewModel.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/chat/ChatViewModel.kt`
- [Prompt builder](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ChatSystemPromptBuilder.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ChatSystemPromptBuilder.kt`
- [AI services](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/Service.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/Service.kt`
- [Interactive UI](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiRenderer.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiRenderer.kt`
- [Text to speech](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiTts.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/dynamicui/KaiUiTts.kt`

### Memory and settings

- [Conversation history](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ConversationStorage.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ConversationStorage.kt`
- [Persistent memory](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/MemoryStore.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/MemoryStore.kt`
- [Assistant settings](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/AppSettingsService.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/AppSettingsService.kt`

### Tools and integrations

- [Tool executor](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ToolExecutor.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/ToolExecutor.kt`
- [Agent tool set](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/AgentToolSet.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/AgentToolSet.kt`
- [MCP servers](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/mcp/McpServerManager.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/mcp/McpServerManager.kt`
- [Skills manager](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/skills/SkillManager.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/skills/SkillManager.kt`
- [Device notifications](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/NotificationTools.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/tools/NotificationTools.kt`

### Autonomous features

- [Heartbeat manager](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/HeartbeatManager.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/HeartbeatManager.kt`
- [Task scheduler](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/TaskScheduler.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/data/TaskScheduler.kt`

### Local runtimes

- [Sandbox interface](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/sandbox/SandboxSessionViewModel.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/ui/sandbox/SandboxSessionViewModel.kt`
- [Linux sandbox](https://github.com/simonschubert/kai/blob/main/composeApp/src/androidMain/kotlin/com/inspiredandroid/kai/sandbox/LinuxSandboxManager.kt): `composeApp/src/androidMain/kotlin/com/inspiredandroid/kai/sandbox/LinuxSandboxManager.kt`
- [On-device inference](https://github.com/simonschubert/kai/blob/main/composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/inference/LocalInferenceEngine.kt): `composeApp/src/commonMain/kotlin/com/inspiredandroid/kai/inference/LocalInferenceEngine.kt`

### Other components

- **User**
- **AI provider**

## Connections

- User → Chat interface: sends message
- Chat interface → Chat workflow: submits input
- Chat workflow → Prompt builder: builds prompt
- Chat workflow → Persistent memory: recalls and stores
- Chat workflow → Conversation history: loads and saves
- Chat workflow → AI services: selects service
- Chat workflow → AI provider: requests completion
- AI provider → Chat workflow: returns response
- Chat workflow → Tool executor: dispatches calls
- Tool executor → Agent tool set: runs tools
- Agent tool set → MCP servers: uses configured servers
- Chat workflow → Interactive UI: renders generated UI
- Chat workflow → On-device inference: uses local inference
- Chat workflow → Text to speech: reads responses
- Heartbeat manager → Persistent memory: reviews memories
- Heartbeat manager → Task scheduler: reviews pending tasks
- Heartbeat manager → AI provider: requests self-check
- Heartbeat manager → Device notifications: surfaces attention
- Assistant settings → Chat workflow: configures assistant
- Sandbox interface → Linux sandbox: controls environment
- Tool executor → Linux sandbox: runs shell commands
- Skills manager → Linux sandbox: loads and installs skills