# ayr1k/luma architecture

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

- Interactive diagram: https://gitdiagram.com/ayr1k/luma
- Repository: https://github.com/ayr1k/luma
- Video tour (about a minute): https://gitdiagram.com/ayr1k/luma/video

## Overview

Luma is a Windows desktop AI agent for conversations and project work. Its main workflow is user input through the local client API, asynchronous task execution by AgentCore, model inference and permission-bounded tool use, then persisted results for review. Separate capabilities cover context management, extensions, project/Git workflows, and file previews. The README documents additional UI and product behavior beyond the sampled excerpts; the graph uses documented relationships where implementation wiring was not shown.

Main entry points: [`local_agent/service.py`](https://github.com/ayr1k/luma/blob/main/local_agent/service.py) (Local API), [`local_agent/core.py`](https://github.com/ayr1k/luma/blob/main/local_agent/core.py) (Agent Core), [`local_agent/tools.py`](https://github.com/ayr1k/luma/blob/main/local_agent/tools.py) (Tool execution), [`local_agent/builtin_tools.py`](https://github.com/ayr1k/luma/blob/main/local_agent/builtin_tools.py) (Built-in tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_desktop["Desktop client<br/>[desktop.py]"]
  node_api["Local API<br/>[service.py]"]
  node_preferences["Model settings<br/>[preferences.py]"]
  node_model_profiles["Model profiles<br/>[model_profiles.py]"]
end

subgraph group_agent["Agent execution"]
  node_tasks["Task runner<br/>[tasks.py]"]
  node_core["Agent Core<br/>[core.py]"]
  node_model["Inference client<br/>[model.py]"]
  node_tools["Tool execution<br/>[tools.py]"]
  node_builtin_tools["Built-in tools<br/>[builtin_tools.py]"]
  node_attachments["Attachments<br/>[attachments.py]"]
end

subgraph group_project["Project operations"]
  node_storage[("Session storage<br/>[storage.py]")]
  node_files["Project files<br/>[files.py]"]
  node_search["Web search<br/>[search.py]"]
  node_git["Git operations<br/>[git_manager.py]"]
  node_preview["Change preview<br/>[code_preview.py]"]
end

subgraph group_extensions["Extensions and context"]
  node_context["Context management<br/>[context.py]"]
  node_extensions_manager["Extensions and Skills<br/>[extensions.py]"]
  node_plugin_worker["Plugin worker<br/>[plugin_worker.py]"]
  node_presets["Preset plugins<br/>[main.py]"]
end

node_user(("User"))
node_inference_service(("Inference service"))
node_filesystem[("Local workspace")]
node_git_remote(("Git remote"))

node_user -->|"uses"| node_desktop
node_desktop -->|"requests"| node_api
node_api -->|"configures"| node_preferences
node_api -->|"manages"| node_model_profiles
node_api -->|"starts tasks"| node_tasks
node_tasks -->|"runs action"| node_core
node_core -->|"requests inference"| node_model
node_model -->|"sends prompts"| node_inference_service
node_core -->|"dispatches tools"| node_tools
node_tools -->|"dispatches built-ins"| node_builtin_tools
node_core -->|"prepares input"| node_attachments
node_core -->|"persists session"| node_storage
node_api -->|"reads projects"| node_storage
node_core -->|"manages context"| node_context
node_builtin_tools -->|"uses file tools"| node_files
node_builtin_tools -.->|"searches web"| node_search
node_tools -->|"resolves extensions"| node_extensions_manager
node_extensions_manager -->|"runs code plugin"| node_plugin_worker
node_plugin_worker -->|"executes entry"| node_presets
node_files -->|"reads and writes"| node_filesystem
node_git -->|"inspects workspace"| node_filesystem
node_api -->|"serves Git actions"| node_git
node_git -->|"fetches and pushes"| node_git_remote
node_api -->|"provides previews"| node_preview

click node_desktop "https://github.com/ayr1k/luma/blob/main/local_agent/desktop.py"
click node_api "https://github.com/ayr1k/luma/blob/main/local_agent/service.py"
click node_preferences "https://github.com/ayr1k/luma/blob/main/local_agent/preferences.py"
click node_model_profiles "https://github.com/ayr1k/luma/blob/main/local_agent/model_profiles.py"
click node_tasks "https://github.com/ayr1k/luma/blob/main/local_agent/tasks.py"
click node_core "https://github.com/ayr1k/luma/blob/main/local_agent/core.py"
click node_model "https://github.com/ayr1k/luma/blob/main/local_agent/model.py"
click node_tools "https://github.com/ayr1k/luma/blob/main/local_agent/tools.py"
click node_builtin_tools "https://github.com/ayr1k/luma/blob/main/local_agent/builtin_tools.py"
click node_attachments "https://github.com/ayr1k/luma/blob/main/local_agent/attachments.py"
click node_storage "https://github.com/ayr1k/luma/blob/main/local_agent/storage.py"
click node_context "https://github.com/ayr1k/luma/blob/main/local_agent/context.py"
click node_files "https://github.com/ayr1k/luma/blob/main/local_agent/files.py"
click node_search "https://github.com/ayr1k/luma/blob/main/local_agent/search.py"
click node_git "https://github.com/ayr1k/luma/blob/main/local_agent/git_manager.py"
click node_preview "https://github.com/ayr1k/luma/blob/main/local_agent/code_preview.py"
click node_extensions_manager "https://github.com/ayr1k/luma/blob/main/local_agent/extensions.py"
click node_plugin_worker "https://github.com/ayr1k/luma/blob/main/local_agent/plugin_worker.py"
click node_presets "https://github.com/ayr1k/luma/blob/main/preset_plugins/luma-project-overview/main.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_desktop,node_api,node_preferences,node_model_profiles,node_user toneBlue
class node_tasks,node_core,node_model,node_tools,node_builtin_tools,node_attachments,node_filesystem toneAmber
class node_storage,node_files,node_search,node_git,node_preview toneMint
class node_context,node_extensions_manager,node_plugin_worker,node_presets toneRose
class node_inference_service,node_git_remote toneIndigo
```

## Components

### Client and API

- [Desktop client](https://github.com/ayr1k/luma/blob/main/local_agent/desktop.py): `local_agent/desktop.py`
- [Local API](https://github.com/ayr1k/luma/blob/main/local_agent/service.py): `local_agent/service.py`
- [Model settings](https://github.com/ayr1k/luma/blob/main/local_agent/preferences.py): `local_agent/preferences.py`
- [Model profiles](https://github.com/ayr1k/luma/blob/main/local_agent/model_profiles.py): `local_agent/model_profiles.py`

### Agent execution

- [Task runner](https://github.com/ayr1k/luma/blob/main/local_agent/tasks.py): `local_agent/tasks.py`
- [Agent Core](https://github.com/ayr1k/luma/blob/main/local_agent/core.py): `local_agent/core.py`
- [Inference client](https://github.com/ayr1k/luma/blob/main/local_agent/model.py): `local_agent/model.py`
- [Tool execution](https://github.com/ayr1k/luma/blob/main/local_agent/tools.py): `local_agent/tools.py`
- [Built-in tools](https://github.com/ayr1k/luma/blob/main/local_agent/builtin_tools.py): `local_agent/builtin_tools.py`
- [Attachments](https://github.com/ayr1k/luma/blob/main/local_agent/attachments.py): `local_agent/attachments.py`

### Project operations

- [Session storage](https://github.com/ayr1k/luma/blob/main/local_agent/storage.py): `local_agent/storage.py`
- [Project files](https://github.com/ayr1k/luma/blob/main/local_agent/files.py): `local_agent/files.py`
- [Web search](https://github.com/ayr1k/luma/blob/main/local_agent/search.py): `local_agent/search.py`
- [Git operations](https://github.com/ayr1k/luma/blob/main/local_agent/git_manager.py): `local_agent/git_manager.py`
- [Change preview](https://github.com/ayr1k/luma/blob/main/local_agent/code_preview.py): `local_agent/code_preview.py`

### Extensions and context

- [Context management](https://github.com/ayr1k/luma/blob/main/local_agent/context.py): `local_agent/context.py`
- [Extensions and Skills](https://github.com/ayr1k/luma/blob/main/local_agent/extensions.py): `local_agent/extensions.py`
- [Plugin worker](https://github.com/ayr1k/luma/blob/main/local_agent/plugin_worker.py): `local_agent/plugin_worker.py`
- [Preset plugins](https://github.com/ayr1k/luma/blob/main/preset_plugins/luma-project-overview/main.py): `preset_plugins/luma-project-overview/main.py`

### Other components

- **User**
- **Inference service**
- **Local workspace**
- **Git remote**

## Connections

- User → Desktop client: uses
- Desktop client → Local API: requests
- Local API → Model settings: configures
- Local API → Model profiles: manages
- Local API → Task runner: starts tasks
- Task runner → Agent Core: runs action
- Agent Core → Inference client: requests inference
- Inference client → Inference service: sends prompts
- Agent Core → Tool execution: dispatches tools
- Tool execution → Built-in tools: dispatches built-ins
- Agent Core → Attachments: prepares input
- Agent Core → Session storage: persists session
- Local API → Session storage: reads projects
- Agent Core → Context management: manages context
- Built-in tools → Project files: uses file tools
- Built-in tools → Web search: searches web
- Tool execution → Extensions and Skills: resolves extensions
- Extensions and Skills → Plugin worker: runs code plugin
- Plugin worker → Preset plugins: executes entry
- Project files → Local workspace: reads and writes
- Git operations → Local workspace: inspects workspace
- Local API → Git operations: serves Git actions
- Git operations → Git remote: fetches and pushes
- Local API → Change preview: provides previews