fourcolors/luna

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.