DeskLumina

Intelligent Desktop Automation for Linux
Natural Language Control • High Performance • Secure by Design

---

📌 Overview

DeskLumina automates your Linux desktop using Bun and TypeScript. It translates human intent into system execution, letting you control your environment through natural language.

By leveraging a multi-provider AI layer (Groq, OpenAI, Anthropic, Gemini, OpenRouter, Hugging Face) for near-instant inference and Rofi for a lightweight UI, DeskLumina provides a seamless, keyboard-centric experience for launching apps, managing files, and controlling media.

---

🚀 Key Features

• 🪟 Rofi Integration: A lightweight, keyboard-friendly UI that fits perfectly into tiling window managers like i3, bspwm, or sway.
• 🔊 Low-Latency TTS: Near-instant voice responses using the AdaptiveChunker and Edge TTS.
• 🤖 Smart Daemon: A persistent background service that eliminates startup overhead.
• 🛡️ Security Layer: Automatic detection of dangerous commands with interactive confirmation.
• 🔧 Extensible Tools: A modular system for controlling applications, files, media, and more.
• 🌐 Multilingual Support: Fully localized for English, Indonesian, and Japanese.

---

📑 Table of Contents

• Requirements
• Installation
• Quick Start
• Interaction Modes
• Configuration
• Architecture
• Documentation
• License

---

🛠️ Requirements

Essential

• Bun: High-performance JS/TS runtime (v1.3.9+).
• API Key: At least one provider key (Groq, OpenAI, Anthropic, Gemini, OpenRouter, or Hugging Face).
• Rofi: Standard Linux distribution package for the UI.

Optional (Feature-dependent)

• mpc: For media control (requires mpd).
• clipcat: For clipboard management.
• dunst: For system notifications (dunstify).

---

💾 Installation

# 1. Clone the repository
git clone https://github.com/Rafacuy/desklumina.git ~/.config/desklumina
cd ~/.config/desklumina

# 2. Install dependencies
bun install

# 3. Setup environment
cp .env.example .env

Important

Edit your .env file and add at least one provider API key and your preferred DESKLUMINA_MODEL (format: provider:model).

---

⚡ Quick Start

Launch the interactive UI and try these commands:

bun run start

• App: "open browser" or "launch telegram"
• Files: "list files in ~/Downloads" or "create a folder named Work"
• Math: "what is 15% of 340?" or "convert 100 km to miles"
• Media: "play music" or "volume 50"
• System: "what's the current date?"

---

🔄 Interaction Modes

DeskLumina supports multiple ways to interact with your system:

Mode	Command	Description
Interactive UI	bun run start	The standard Rofi-based chat loop.
Terminal Loop	bun run dev	A persistent chat interface in your terminal.
One-Off Exec	bun run start -- --exec "cmd"	Execute a single command and exit.
Daemon	bun run daemon	Run as a background service for instant response.
Send to Daemon	bun run send "cmd"	Communicate with the running daemon.

---

⚙️ Configuration

DeskLumina is customizable through three primary files:

• .env: API keys and core model configuration.
• settings.json: UI preferences, language, TTS settings, and security toggles.
• src/config/apps.json: Custom application aliases and system commands.

Tip

Access the Settings menu directly in the Rofi UI by pressing Tab.

---

🧠 Architecture

DeskLumina uses a modular design to separate intelligence from execution:

flowchart TD
    subgraph Frontend ["User Interface"]
        UI["Rofi / Terminal / Daemon"]
    end

    subgraph Logic ["Core Orchestrator"]
        Core["Lumina / ChatManager / i18n"]
    end

    subgraph Backend ["Execution & Intelligence"]
        AI["AI Layer - Multi-Provider"]
        Security["Security Layer"]
        Tools["Tools Layer - Desktop"]
    end

    UI --> Core
    Core --> AI
    Core --> Security
    Core --> Tools

    style Frontend fill:#f9f9f9,stroke:#333
    style Logic fill:#f9f9f9,stroke:#333
    style Backend fill:#f9f9f9,stroke:#333

Loading

📚 Documentation

Detailed guides are available in the docs/ folder:

1. 📖 Introduction
2. ⚙️ Installation Guide
3. 🚀 Quick Start
4. 🔧 Configuration
5. 🧠 Architecture
6. 🎮 Usage Guide
7. 🛠️ Tools Reference
8. 🔌 API Reference
9. 🛡️ Security Model
10. 💻 Development
11. 🔄 Daemon Mode
12. 🧪 Testing
13. 🔍 Troubleshooting
14. ❓ FAQ
15. 🤝 Contributing
16. 🗺️ Roadmap

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Made with ❤️ for the Linux Community