# lunarstack-co/aldwin architecture

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

- Interactive diagram: https://gitdiagram.com/lunarstack-co/aldwin
- Repository: https://github.com/lunarstack-co/aldwin

## Overview

Aldwin is a local-first terminal assistant. A user starts the CLI, which bootstraps onboarding and sends requests through a client interface to the host; the host runs agent turns, applies tool-safety policy, and persists sessions. The documented capabilities branch into files and documents, memory and persona, web search, planning, skills, models, and MCP connectors. Evidence for several branches is README-level or comes from imports listed in the source index; unsampled implementation details are not treated as verified call relationships.

Main entry points: [`src/aldwin/host/runner.py`](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/runner.py) (Turn runner), [`src/aldwin/host/in_process.py`](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/in_process.py) (In-process host), [`src/aldwin/host/connectors.py`](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/connectors.py) (MCP connectors), [`src/aldwin/client/client.py`](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/client/client.py) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Terminal experience"]
  node_cli["CLI and chat<br/>[main.py]"]
  node_client["Client API<br/>[client.py]"]
  node_protocol["Message protocol<br/>[messages.py]"]
end

subgraph group_runtime["Host and agent"]
  node_host["In-process host<br/>[in_process.py]"]
  node_runner["Turn runner<br/>[runner.py]"]
  node_agent["Agent engine<br/>[agent.py]"]
  node_safety["Tool safety<br/>[policy.py]"]
  node_approval_log[("Approval log<br/>[approval_log.py]")]
  node_sessions[("Session history<br/>[sessions.py]")]
end

subgraph group_context["User context"]
  node_workspace["Workspace access<br/>[workspace.py]"]
  node_memory[("Memory and notes<br/>[memory.py]")]
  node_persona["Persona profile<br/>[persona.py]"]
  node_settings[("Settings and secrets<br/>[settings.py]")]
end

subgraph group_capabilities["Assistant capabilities"]
  node_tools["Tool registry<br/>[__init__.py]"]
  node_files["Files and documents<br/>[files.py]"]
  node_web["Web search<br/>[shared.py]"]
  node_skills["Skills<br/>[skills.py]"]
end

subgraph group_integrations["Models and connectors"]
  node_providers["Model providers<br/>[registry.py]"]
  node_connectors["MCP connectors<br/>[connectors.py]"]
  node_connector_config[("Connector config<br/>[config.py]")]
  node_oauth[("OAuth tokens<br/>[token_storage.py]")]
end

node_user(("User"))
node_model_service(("Model service"))
node_mcp_service{{"MCP servers"}}

node_user -->|"starts chat"| node_cli
node_cli -->|"creates client"| node_client
node_client -->|"exchanges messages"| node_protocol
node_client -->|"uses transport"| node_host
node_host -.->|"dispatches turns"| node_runner
node_runner -->|"runs agent"| node_agent
node_runner -->|"applies policy"| node_safety
node_safety -->|"records decisions"| node_approval_log
node_runner -.->|"manages history"| node_sessions
node_runner -->|"uses workspace"| node_workspace
node_runner -->|"loads memory"| node_memory
node_runner -->|"loads persona"| node_persona
node_host -->|"loads settings"| node_settings
node_runner -->|"registers tools"| node_tools
node_tools -->|"provides file tools"| node_files
node_user -.->|"requests file work"| node_files
node_tools -->|"provides search"| node_web
node_user -.->|"requests web search"| node_web
node_runner -->|"loads skills"| node_skills
node_user -.->|"selects skill"| node_skills
node_host -->|"discovers providers"| node_providers
node_providers -.->|"sends model requests"| node_model_service
node_runner -->|"handles connectors"| node_connectors
node_connectors -.->|"reads configuration"| node_connector_config
node_connectors -.->|"stores credentials"| node_oauth
node_connectors -.->|"invokes tools"| node_mcp_service

click node_cli "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/cli/main.py"
click node_client "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/client/client.py"
click node_protocol "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/protocol/messages.py"
click node_host "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/in_process.py"
click node_runner "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/runner.py"
click node_agent "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/agent.py"
click node_safety "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/policy.py"
click node_approval_log "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/approval_log.py"
click node_sessions "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/sessions.py"
click node_workspace "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/workspace.py"
click node_memory "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/memory.py"
click node_persona "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/persona.py"
click node_settings "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/settings.py"
click node_tools "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/__init__.py"
click node_files "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/files.py"
click node_web "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/web_search/shared.py"
click node_skills "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/skills.py"
click node_providers "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/providers/registry.py"
click node_connectors "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/connectors.py"
click node_connector_config "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/connectors/config.py"
click node_oauth "https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/connectors/token_storage.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_client,node_protocol,node_user toneBlue
class node_host,node_runner,node_agent,node_safety,node_approval_log,node_sessions toneAmber
class node_workspace,node_memory,node_persona,node_settings,node_mcp_service toneMint
class node_tools,node_files,node_web,node_skills toneRose
class node_providers,node_connectors,node_connector_config,node_oauth,node_model_service toneIndigo
```

## Components

### Terminal experience

- [CLI and chat](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/cli/main.py): `src/aldwin/cli/main.py`
- [Client API](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/client/client.py): `src/aldwin/client/client.py`
- [Message protocol](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/protocol/messages.py): `src/aldwin/protocol/messages.py`

### Host and agent

- [In-process host](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/in_process.py): `src/aldwin/host/in_process.py`
- [Turn runner](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/runner.py): `src/aldwin/host/runner.py`
- [Agent engine](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/agent.py): `src/aldwin/core/agent.py`
- [Tool safety](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/policy.py): `src/aldwin/core/policy.py`
- [Approval log](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/approval_log.py): `src/aldwin/core/approval_log.py`
- [Session history](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/sessions.py): `src/aldwin/host/sessions.py`

### User context

- [Workspace access](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/workspace.py): `src/aldwin/core/workspace.py`
- [Memory and notes](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/memory.py): `src/aldwin/core/memory.py`
- [Persona profile](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/persona.py): `src/aldwin/core/persona.py`
- [Settings and secrets](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/settings.py): `src/aldwin/core/settings.py`

### Assistant capabilities

- [Tool registry](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/__init__.py): `src/aldwin/core/tools/__init__.py`
- [Files and documents](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/files.py): `src/aldwin/core/tools/files.py`
- [Web search](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/tools/web_search/shared.py): `src/aldwin/core/tools/web_search/shared.py`
- [Skills](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/skills.py): `src/aldwin/core/skills.py`

### Models and connectors

- [Model providers](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/providers/registry.py): `src/aldwin/core/providers/registry.py`
- [MCP connectors](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/host/connectors.py): `src/aldwin/host/connectors.py`
- [Connector config](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/connectors/config.py): `src/aldwin/core/connectors/config.py`
- [OAuth tokens](https://github.com/lunarstack-co/aldwin/blob/main/src/aldwin/core/connectors/token_storage.py): `src/aldwin/core/connectors/token_storage.py`

### Other components

- **User**
- **Model service**
- **MCP servers**

## Connections

- User → CLI and chat: starts chat (evidence: `README.md`)
- CLI and chat → Client API: creates client (evidence: `src/aldwin/cli/main.py`)
- Client API → Message protocol: exchanges messages (evidence: `src/aldwin/client/client.py`)
- Client API → In-process host: uses transport (evidence: `src/aldwin/client/client.py`)
- In-process host → Turn runner: dispatches turns (evidence: `src/aldwin/host/in_process.py`)
- Turn runner → Agent engine: runs agent (evidence: `src/aldwin/host/runner.py`)
- Turn runner → Tool safety: applies policy (evidence: `src/aldwin/host/runner.py`)
- Tool safety → Approval log: records decisions (evidence: `src/aldwin/core/policy.py`)
- Turn runner → Session history: manages history (evidence: `src/aldwin/host/runner.py`)
- Turn runner → Workspace access: uses workspace (evidence: `src/aldwin/host/runner.py`)
- Turn runner → Memory and notes: loads memory (evidence: `src/aldwin/host/runner.py`)
- Turn runner → Persona profile: loads persona (evidence: `src/aldwin/host/runner.py`)
- In-process host → Settings and secrets: loads settings (evidence: `src/aldwin/host/in_process.py`)
- Turn runner → Tool registry: registers tools (evidence: `src/aldwin/host/runner.py`)
- Tool registry → Files and documents: provides file tools (evidence: `src/aldwin/core/tools/__init__.py`)
- User → Files and documents: requests file work (evidence: `README.md`)
- Tool registry → Web search: provides search (evidence: `src/aldwin/core/tools/__init__.py`)
- User → Web search: requests web search (evidence: `README.md`)
- Turn runner → Skills: loads skills (evidence: `src/aldwin/host/runner.py`)
- User → Skills: selects skill (evidence: `README.md`)
- In-process host → Model providers: discovers providers (evidence: `src/aldwin/host/in_process.py`)
- Model providers → Model service: sends model requests
- Turn runner → MCP connectors: handles connectors (evidence: `src/aldwin/host/runner.py`)
- MCP connectors → Connector config: reads configuration
- MCP connectors → OAuth tokens: stores credentials
- MCP connectors → MCP servers: invokes tools