How lunarstack-co/aldwin works
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: runner.py Turn runner · in_process.py In-process host · connectors.py MCP connectors · client.py Client API
Components 24
Terminal experience
- CLI and chat
src/aldwin/cli/main.py - Client API
src/aldwin/client/client.py - Message protocol
src/aldwin/protocol/messages.py
Host and agent
- In-process host
src/aldwin/host/in_process.py - Turn runner
src/aldwin/host/runner.py - Agent engine
src/aldwin/core/agent.py - Tool safety
src/aldwin/core/policy.py - Approval log
src/aldwin/core/approval_log.py - Session history
src/aldwin/host/sessions.py
User context
- Workspace access
src/aldwin/core/workspace.py - Memory and notes
src/aldwin/core/memory.py - Persona profile
src/aldwin/core/persona.py - Settings and secrets
src/aldwin/core/settings.py
Assistant capabilities
- Tool registry
src/aldwin/core/tools/__init__.py - Files and documents
src/aldwin/core/tools/files.py - Web search
src/aldwin/core/tools/web_search/shared.py - Skills
src/aldwin/core/skills.py
Models and connectors
- Model providers
src/aldwin/core/providers/registry.py - MCP connectors
src/aldwin/host/connectors.py - Connector config
src/aldwin/core/connectors/config.py - OAuth tokens
src/aldwin/core/connectors/token_storage.py
Other components
- User
- Model service
- MCP servers
Connections 26
- User → CLI and chat: starts chat
README.md - CLI and chat → Client API: creates client
src/aldwin/cli/main.py - Client API → Message protocol: exchanges messages
src/aldwin/client/client.py - Client API → In-process host: uses transport
src/aldwin/client/client.py - In-process host → Turn runner: dispatches turns
src/aldwin/host/in_process.py - Turn runner → Agent engine: runs agent
src/aldwin/host/runner.py - Turn runner → Tool safety: applies policy
src/aldwin/host/runner.py - Tool safety → Approval log: records decisions
src/aldwin/core/policy.py - Turn runner → Session history: manages history
src/aldwin/host/runner.py - Turn runner → Workspace access: uses workspace
src/aldwin/host/runner.py - Turn runner → Memory and notes: loads memory
src/aldwin/host/runner.py - Turn runner → Persona profile: loads persona
src/aldwin/host/runner.py - In-process host → Settings and secrets: loads settings
src/aldwin/host/in_process.py - Turn runner → Tool registry: registers tools
src/aldwin/host/runner.py - Tool registry → Files and documents: provides file tools
src/aldwin/core/tools/__init__.py - User → Files and documents: requests file work
README.md - Tool registry → Web search: provides search
src/aldwin/core/tools/__init__.py - User → Web search: requests web search
README.md - Turn runner → Skills: loads skills
src/aldwin/host/runner.py - User → Skills: selects skill
README.md - In-process host → Model providers: discovers providers
src/aldwin/host/in_process.py - Model providers → Model service: sends model requests
- Turn runner → MCP connectors: handles connectors
src/aldwin/host/runner.py - MCP connectors → Connector config: reads configuration
- MCP connectors → OAuth tokens: stores credentials
- MCP connectors → MCP servers: invokes tools