# fourcolors/luna architecture

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

- Interactive diagram: https://gitdiagram.com/fourcolors/luna
- Repository: https://github.com/fourcolors/luna

## Overview

1. **Overall shape**
   Luna is a Bun + Effect-TS monorepo organized around a shared server/runtime core and multiple client surfaces. The core business logic lives in `packages/core`, while `apps/*` are presentation/entrypoint layers and `packages/*-tools` expose capabilities to agents over MCP-style tool servers.

2. **Primary runtime boundary**
   The main deployment boundary is the **Luna server** versus local clients. The server runs the agent/session/memory/workflow machinery and exposes a WebSocket UI/control surface. Clients are the terminal app (`apps/agent-cli`), the Solid web app (`apps/ui-web`), and the Tauri desktop widget (`apps/ui-moon-tauri`).

3. **Shared domain core**
   `packages/core` holds the durable backend subsystems: session storage, job scheduling, workflow runtime, account brokering, memory, observability, cost accounting, suggested actions, beliefs/alignment, skill registry, secret providers, and provider routing/config. This is the architectural center that everything else composes through Effect layers.

4. **Agent execution path**
   The agent loop is split across `packages/chat-service`, `packages/adapter-sdk`, and the `packages/core` services. Chat requests flow through the chat service into the Anthropic Claude Code Agent SDK bridge, with tool wiring, env overlays, and account/token selection supplied by the broker and secret layers.

5. **Account and secret management**
   Authentication is OAuth-based through Claude Code, not a direct Anthropic API key. `AccountBroker` manages token rotation and health; secret storage is abstracted through keychain/1Password/file/env backends in `packages/core/src/secret-provider`. This is a key trust boundary because the client does not own the Claude token lifecycle.

6. **Persistence and state**
   Runtime state is mostly local and SQLite-backed. `packages/core/src/db`, `session`, `threads`, `jobs`, `telemetry`, `cost-accounting`, `dream`, `alignment`, and related stores persist durable state under `~/.luna/`. Memory uses its own backend abstraction in `packages/memory`, including SQLite/vector variants and file/in-memory fallbacks.

7. **Memory and retrieval**
   Persistent memory is a separate subsystem surfaced to agents via `packages/memory-tools`. The memory package provides the storage/retrieval layer, including vector search and bootstrap/maintenance logic, while the tools package turns that into callable agent actions. Local embeddings are supported; chat itself is still cloud Claude.

8. **Scheduling and background work**
   Background behavior is centralized in `JobTicker` and the worker registry in `packages/core/src/jobs`. It drains the jobs table and dispatches due work such as prompt, workflow, dream, and wake tasks. This gives the system a single supervised scheduler rather than many ad hoc timers.

9. **UI architecture**
   The UI is multi-surface but shares presentation/state concepts. `packages/ui-shared` and `packages/ui-shared-solid` contain reusable components and reducers, while `packages/ui-ws` provides the WebSocket protocol/server that feeds chat, vault, skills, suggestions, widgets, and workflow galleries to the browser and desktop clients.

10. **Desktop widget and web app**
   `apps/ui-moon-tauri` is a Rust/Tauri desktop shell with a lightweight floating widget and panels. It talks to the server over the shared WebSocket protocol and is guarded by Tauri capabilities/permissions. `apps/ui-web` is the browser/Solid app and also hosts some setup flows, install helpers, and chat-server side scripts.

11. **CLI and terminal client**
   `apps/agent-cli` is the `luna` terminal client. It covers chat, doctor/preflight, account management, memory, pairing, and recovery flows. It is mostly a thin client over the server WebSocket/API, with local config in `~/.luna/.env` and shell/TUI helpers for interactive use.

12. **Tooling and external integrations**
   The repo has many purpose-built tool servers: local shell, memory, scheduler, secret, observability, widget, job-input, and skill tools. `packages/connectors` adds external app integrations like GitHub, Slack, and Google Workspace via OAuth/store/catalog abstractions. `packages/channel*` handle message delivery/session mapping for channel integrations.

13. **Control and transport boundaries**
   `packages/control-server` is a separate control plane from the UI/chat plane. The system uses WebSocket transport for UI communication and explicitly treats it as private-network traffic, typically behind Tailscale. This matters architecturally because the remote server/client pairing and token flow are part of the deployment model, not just app config.

14. **Local host/runtime operations**
   The repo includes concrete deployment scripts for install, server boot, container creation, restart, and release. Stable and dev runtimes are managed separately, often via Incus containers or launchd on macOS, with local state under `~/.luna`, `~/.luna-dev`, and related runtime paths.

15. **Release and verification model**
   Releases are tag-driven, especially for the Moon desktop app (`moon-v*` tags). CI and release workflows build, sign, and publish artifacts, while the repo also includes focused smoke tests, deployment verifiers, and boot probes to validate runtime behavior end-to-end.

Main entry points: [`packages/ui-ws`](https://github.com/fourcolors/luna/tree/master/packages/ui-ws) (UI WS), [`packages/core/src`](https://github.com/fourcolors/luna/tree/master/packages/core/src) (Domain Core), [`packages/chat-service`](https://github.com/fourcolors/luna/tree/master/packages/chat-service) (Chat Service), [`packages/adapter-sdk`](https://github.com/fourcolors/luna/tree/master/packages/adapter-sdk) (Adapter SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_apps["Apps"]
  node_node_agent_cli["Agent CLI<br/>terminal client"]
  node_node_ui_web["UI Web<br/>solid app"]
  node_node_ui_tauri["Moon Tauri<br/>desktop shell"]
end

subgraph group_group_core["Core"]
  node_node_core_session[("Session Core<br/>session/runtime")]
  node_node_core_jobs["Job Engine<br/>scheduler"]
  node_node_core_agent{{"Agent Broker<br/>account routing"}}
  node_node_core_memory[("Memory Core<br/>memory backend")]
  node_node_core_domain["Domain Core<br/>business services"]
  node_node_core_db[("SQLite State<br/>persistence")]
  node_node_core_secrets{{"Secret Provider<br/>secret backends"}}
  node_node_chat_service["Chat Service<br/>chat orchestration"]
  node_node_adapter_sdk["Adapter SDK<br/>claude bridge"]
  node_node_control_server["Control Server<br/>control plane"]
end

subgraph group_group_ui["UI"]
  node_node_ws["UI WS<br/>websocket protocol"]
  node_node_ui_shared["UI Shared<br/>state/model layer"]
  node_node_ui_shared_solid["UI Solid<br/>solid components"]
end

subgraph group_group_tools["Tools"]
  node_node_local_shell_tools["Shell Tools<br/>tool server"]
  node_node_memory_tools["Memory Tools<br/>tool server"]
  node_node_scheduler_tools["Scheduler Tools<br/>tool server"]
  node_node_secret_tools["Secret Tools<br/>tool server"]
  node_node_widget_tools["Widget Tools<br/>tool server"]
  node_node_connectors["Connectors<br/>external integrations"]
end

subgraph group_group_ops["Ops"]
  node_node_scripts["Ops Scripts<br/>deploy/install"]
end

node_node_agent_cli -->|"chat/ui"| node_node_ws
node_node_ui_web -->|"chat/ui"| node_node_ws
node_node_ui_tauri -->|"chat/ui"| node_node_ws
node_node_ws -->|"frames"| node_node_ui_shared
node_node_ui_shared -->|"components"| node_node_ui_shared_solid
node_node_ws -->|"turns"| node_node_chat_service
node_node_chat_service -->|"agent turns"| node_node_adapter_sdk
node_node_chat_service -->|"accounts"| node_node_core_agent
node_node_chat_service -->|"sessions"| node_node_core_session
node_node_adapter_sdk -->|"workers"| node_node_core_domain
node_node_adapter_sdk -.->|"memory"| node_node_memory_tools
node_node_core_domain -->|"state"| node_node_core_db
node_node_core_domain -->|"secrets"| node_node_core_secrets
node_node_core_domain -->|"retrieval"| node_node_core_memory
node_node_core_domain -->|"background"| node_node_core_jobs
node_node_core_jobs -.->|"tools"| node_node_scheduler_tools
node_node_core_memory -->|"mcp"| node_node_memory_tools
node_node_core_secrets -->|"mcp"| node_node_secret_tools
node_node_core_jobs -->|"workers"| node_node_core_domain
node_node_connectors -.->|"integrations"| node_node_ws
node_node_control_server -.->|"control"| node_node_ws
node_node_scripts -.->|"install"| node_node_agent_cli
node_node_scripts -.->|"deploy"| node_node_ws
node_node_scripts -.->|"release"| node_node_ui_tauri
node_node_widget_tools -->|"widgets"| node_node_ui_tauri
node_node_local_shell_tools -->|"exec"| node_node_adapter_sdk
node_node_core_memory -.->|"search"| node_node_ws
node_node_core_session -.->|"sync"| node_node_ws

click node_node_agent_cli "https://github.com/fourcolors/luna/tree/master/apps/agent-cli"
click node_node_ui_web "https://github.com/fourcolors/luna/tree/master/apps/ui-web"
click node_node_ui_tauri "https://github.com/fourcolors/luna/tree/master/apps/ui-moon-tauri"
click node_node_core_session "https://github.com/fourcolors/luna/tree/master/packages/core/src/session"
click node_node_core_jobs "https://github.com/fourcolors/luna/tree/master/packages/core/src/jobs"
click node_node_core_agent "https://github.com/fourcolors/luna/tree/master/packages/core/src/account-broker"
click node_node_core_memory "https://github.com/fourcolors/luna/tree/master/packages/memory"
click node_node_core_domain "https://github.com/fourcolors/luna/tree/master/packages/core/src"
click node_node_core_db "https://github.com/fourcolors/luna/tree/master/packages/core/src/db"
click node_node_core_secrets "https://github.com/fourcolors/luna/tree/master/packages/core/src/secret-provider"
click node_node_chat_service "https://github.com/fourcolors/luna/tree/master/packages/chat-service"
click node_node_adapter_sdk "https://github.com/fourcolors/luna/tree/master/packages/adapter-sdk"
click node_node_ws "https://github.com/fourcolors/luna/tree/master/packages/ui-ws"
click node_node_ui_shared "https://github.com/fourcolors/luna/tree/master/packages/ui-shared"
click node_node_ui_shared_solid "https://github.com/fourcolors/luna/tree/master/packages/ui-shared-solid"
click node_node_local_shell_tools "https://github.com/fourcolors/luna/tree/master/packages/local-shell-tools"
click node_node_memory_tools "https://github.com/fourcolors/luna/tree/master/packages/memory-tools"
click node_node_scheduler_tools "https://github.com/fourcolors/luna/tree/master/packages/scheduler-tools"
click node_node_secret_tools "https://github.com/fourcolors/luna/tree/master/packages/secret-tools"
click node_node_widget_tools "https://github.com/fourcolors/luna/tree/master/packages/widget-tools"
click node_node_connectors "https://github.com/fourcolors/luna/tree/master/packages/connectors"
click node_node_control_server "https://github.com/fourcolors/luna/tree/master/packages/control-server"
click node_node_scripts "https://github.com/fourcolors/luna/tree/master/scripts"

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_node_agent_cli,node_node_ui_web,node_node_ui_tauri toneBlue
class node_node_core_session,node_node_core_jobs,node_node_core_agent,node_node_core_memory,node_node_core_domain,node_node_core_db,node_node_core_secrets,node_node_chat_service,node_node_adapter_sdk,node_node_control_server toneAmber
class node_node_ws,node_node_ui_shared,node_node_ui_shared_solid toneMint
class node_node_local_shell_tools,node_node_memory_tools,node_node_scheduler_tools,node_node_secret_tools,node_node_widget_tools,node_node_connectors toneRose
class node_node_scripts toneIndigo
```

## Components

### Apps

Client surfaces and entrypoints

- [Agent CLI](https://github.com/fourcolors/luna/tree/master/apps/agent-cli): terminal client · Bun-based terminal and chat client · `apps/agent-cli`
- [UI Web](https://github.com/fourcolors/luna/tree/master/apps/ui-web): solid app · Browser client and setup surface · `apps/ui-web`
- [Moon Tauri](https://github.com/fourcolors/luna/tree/master/apps/ui-moon-tauri): desktop shell · Rust/Tauri widget and panel host · `apps/ui-moon-tauri`

### Core

Shared runtime, domain, and state services

- [Session Core](https://github.com/fourcolors/luna/tree/master/packages/core/src/session): session/runtime · Sessions, threads, and history projection · `packages/core/src/session`
- [Job Engine](https://github.com/fourcolors/luna/tree/master/packages/core/src/jobs): scheduler · Ticker, queue, and worker registry · `packages/core/src/jobs`
- [Agent Broker](https://github.com/fourcolors/luna/tree/master/packages/core/src/account-broker): account routing · Account brokering, rotation, and spend control · `packages/core/src/account-broker`
- [Memory Core](https://github.com/fourcolors/luna/tree/master/packages/memory): memory backend · Durable memory storage and retrieval backends · `packages/memory`
- [Domain Core](https://github.com/fourcolors/luna/tree/master/packages/core/src): business services · Alignment, beliefs, dream, wake, skills, actions, telemetry, artifacts · `packages/core/src`
- [SQLite State](https://github.com/fourcolors/luna/tree/master/packages/core/src/db): persistence · SQLite bootstrap and schema-versioned state store · `packages/core/src/db`
- [Secret Provider](https://github.com/fourcolors/luna/tree/master/packages/core/src/secret-provider): secret backends · Keychain, 1Password, file, env, and login plumbing · `packages/core/src/secret-provider`
- [Chat Service](https://github.com/fourcolors/luna/tree/master/packages/chat-service): chat orchestration · Chat session lifecycle and turn coordination · `packages/chat-service`
- [Adapter SDK](https://github.com/fourcolors/luna/tree/master/packages/adapter-sdk): claude bridge · Bridge to Claude Code Agent SDK and worker adapters · `packages/adapter-sdk`
- [Control Server](https://github.com/fourcolors/luna/tree/master/packages/control-server): control plane · Separate private control-plane server · `packages/control-server`

### UI

Shared presentation and transport layers

- [UI WS](https://github.com/fourcolors/luna/tree/master/packages/ui-ws): websocket protocol · Shared WebSocket server and frame protocol for clients · `packages/ui-ws`
- [UI Shared](https://github.com/fourcolors/luna/tree/master/packages/ui-shared): state/model layer · Transport, reducer, streaming, and widget host primitives · `packages/ui-shared`
- [UI Solid](https://github.com/fourcolors/luna/tree/master/packages/ui-shared-solid): solid components · Reusable Solid panels and widgets · `packages/ui-shared-solid`

### Tools

MCP-style capability servers

- [Shell Tools](https://github.com/fourcolors/luna/tree/master/packages/local-shell-tools): tool server · Local shell execution tools exposed to agents · `packages/local-shell-tools`
- [Memory Tools](https://github.com/fourcolors/luna/tree/master/packages/memory-tools): tool server · Agent-facing memory search and mutation tools · `packages/memory-tools`
- [Scheduler Tools](https://github.com/fourcolors/luna/tree/master/packages/scheduler-tools): tool server · Job and schedule operations exposed as tools · `packages/scheduler-tools`
- [Secret Tools](https://github.com/fourcolors/luna/tree/master/packages/secret-tools): tool server · Secret registration and vault actions for agents · `packages/secret-tools`
- [Widget Tools](https://github.com/fourcolors/luna/tree/master/packages/widget-tools): tool server · Widget and UI control tools · `packages/widget-tools`
- [Connectors](https://github.com/fourcolors/luna/tree/master/packages/connectors): external integrations · OAuth-backed GitHub, Slack, and Google Workspace integrations · `packages/connectors`

### Ops

Deployment, release, and verification

- [Ops Scripts](https://github.com/fourcolors/luna/tree/master/scripts): deploy/install · Server install, container, restart, and release scripts · `scripts`

## Connections

- Agent CLI → UI WS: chat/ui · Terminal client talks to the shared websocket surface
- UI Web → UI WS: chat/ui · Browser app consumes websocket frames and setup flows
- Moon Tauri → UI WS: chat/ui · Desktop shell connects over the same protocol
- UI WS → UI Shared: frames · Server emits shared frames into reducers and transport state
- UI Shared → UI Solid: components · Shared state feeds Solid panels and widgets
- UI WS → Chat Service: turns · Chat frames are routed into chat-session orchestration
- Chat Service → Adapter SDK: agent turns · Chat service hands execution to the Claude SDK bridge
- Chat Service → Agent Broker: accounts · Chat orchestration uses brokered account and token selection
- Chat Service → Session Core: sessions · Chat writes and resumes session/thread state
- Adapter SDK → Domain Core: workers · Prompt, dream, wake, and workflow workers depend on shared domain services
- Adapter SDK → Memory Tools: memory · Agent turns can call memory tools through the adapter layer
- Domain Core → SQLite State: state · Durable domain stores persist to SQLite-backed state
- Domain Core → Secret Provider: secrets · Domain services read secret backends through abstraction layers
- Domain Core → Memory Core: retrieval · Persistent memory is a core domain capability
- Domain Core → Job Engine: background · Domain workers are scheduled through the job engine
- Job Engine → Scheduler Tools: tools · Job scheduling is also exposed to agents as a tool surface
- Memory Core → Memory Tools: mcp · Memory storage and search are surfaced through memory tools
- Secret Provider → Secret Tools: mcp · Secret backends are wrapped by secret tool actions
- Job Engine → Domain Core: workers · Ticker dispatches prompt, dream, and wake workers
- Connectors → UI WS: integrations · External account-backed data surfaces are reflected in UI frames
- Control Server → UI WS: control · Separate control plane complements the user-facing websocket plane
- Ops Scripts → Agent CLI: install · Scripts support terminal client and local runtime setup
- Ops Scripts → UI WS: deploy · Scripts boot and restart server/runtime components
- Ops Scripts → Moon Tauri: release · Deployment scripts support desktop packaging and release flows
- Widget Tools → Moon Tauri: widgets · Widget tools back the desktop widget surface
- Shell Tools → Adapter SDK: exec · Local shell capability is available to agent execution flows
- Memory Core → UI WS: search · Memory search and suggestions are broadcast to clients
- Session Core → UI WS: sync · Session and thread state are mirrored into UI views