🌌 Luna — Privacy-First AI Desktop Assistant

Luna is a privacy-focused, premium desktop assistant built on Electron, Vite, and native macOS integrations. By leveraging local LLMs through Ollama and native system APIs, Luna allows you to control your system, organize files, manage your calendar, draft emails, set reminders, and transcribe audio—completely offline, secure, and under your absolute control.

---

✨ Features

• 🔒 Local & Private: All processing is done locally on your machine. Your chats, documents, and voice files never leave your computer.
• ⚡ Heuristic Intent Routing: Standard desktop commands (e.g., launching apps, finding files, creating reminders) are intercepted by a lightweight local heuristic engine. They are executed instantly using macOS scripts, bypassing LLM API latencies and token usage.
• 🤖 Ollama Integration: Fallback chat queries are piped directly into your chosen local model running via Ollama (e.g., Llama 3, Mistral, Qwen, Phi-3).
• 📂 macOS Desktop Automations:
  • Launch Apps: Control apps like Chrome, VS Code, Spotify, Safari, Terminal, and more.
  • Reminders: Add items directly into your native macOS Reminders app.
  • Mail & Calendar: Create drafts in Mail.app and insert events in Calendar.app.
  • Notes & Contacts: Create system notes and look up names in your macOS Contacts.
  • Apple Music Control: Play, pause, skip, and adjust your music system.
  • Spotlight Search: Search your downloads and documents using native Spotlight (mdfind).
  • Smart File Organizer: Automatically categorize cluttered folders (e.g., your Downloads) into dedicated folders (Documents, Images, Code, Audios, Videos, Archives).
• 🎤 Native Voice Suite:
  • Offline Speech-to-Text: Transcribe voice input using Apple's Speech Recognition framework (via a native Swift script).
  • Offline Text-to-Speech: Speak responses using native /usr/bin/say with customizable voices and speeds.
• 🎨 Premium Visuals & UX:
  • Frameless glassmorphic design with native macOS window vibrancy (under-window).
  • Immersive onboarding flow to connect Ollama and select your default model.
  • Context Shelf: Drag and drop files (including full text-extraction for .txt, .md, and .pdf files) directly into your active prompt context.

---

🛠️ Tech Stack

• Core Framework: Electron (v31+) & Node.js
• Frontend Tooling: Vite (v5+)
• Styling: Vanilla CSS (Tailwind-free, using curated HSL color themes & macOS-native glassmorphism effects)
• Local AI Inference: Ollama API (/api/chat)
• Native Automation: AppleScript, shell commands, Spotlight (mdfind)
• Audio Transcription: Swift (using Apple's Speech framework)

---

🚀 Getting Started

Prerequisites

1. macOS: Native speech recognition, say voices, and AppleScript automations require macOS.
2. Ollama: Download and install Ollama. Start it and download a local LLM of your choice (e.g., llama3, mistral, or qwen):

   ollama run llama3

Setup & Run

1. Clone the repository:

   git clone https://github.com/rishu685/Luna-ai.git
   cd Luna-ai

2. Install dependencies:

   npm install

3. Build the frontend assets: (Note: Electron loads the interface from dist/index.html directly, so you must compile the Vite build before running the application)

   npm run build

4. Launch the application:

   npm run start

---

📋 Available Commands & Scripts

• npm run dev: Start the Vite dev server for testing styles in the browser.
• npm run build: Compile and optimize static assets for Electron.
• npm run start: Launch the Electron application.
• npm run package: Package the application into a standalone macOS .app bundle using electron-packager.

---

📂 Project Architecture

.
├── index.html                 # Main window markup
├── main.js                    # Electron main process (IPC handlers & macOS system bridges)
├── preload.js                 # IPC bridge/API exposure to front-end renderer
├── transcribe.swift           # Native Swift command-line utility for offline transcription
├── extend.plist               # Entitlements & system permissions configuration plist
├── vite.config.js             # Vite packaging settings
├── package.json               # Scripts and dependencies
└── src/
    ├── css/
    │   └── index.css          # Glassmorphic style engine, theme configurations & layouts
    └── js/
        ├── app.js             # Bootstrapper that initializes client services
        ├── automation.js      # Front-end adapter for system IPC handlers
        ├── chat.js            # Chat UI controller, drag-and-drop & LLM streaming logic
        ├── memory.js          # Persistent JSON storage & profile manager
        ├── ui.js              # Screens, sidebar actions, and layout controllers
        └── voice.js           # Client-side audio recording & speech controllers

---

🔒 Security & Permissions

Luna requests the following system privileges when launched:

• Microphone Access: Required for speech-to-text recording.
• Speech Recognition: Used by macOS Speech framework to transcribe audio files offline.
• Automation Control: Permissions to control applications via AppleScript (granted per-application or globally upon prompt).

---

📄 License

This project is licensed under the MIT License.