🌌 Lumina: Autonomous AI Coding Agent for VS Code

Illuminating the Path from Idea to Implementation through Local Intelligence & Complete Data Sovereignty.

Features • Architecture • Quickstart • Hardware Profiles • Commands & Shortcuts • Contributing

📖 Table of Contents

• Executive Summary
• Zero-Leak Data Sovereignty
• Key Features
  • 1. The Nexus (Glassmorphic Sidebar)
  • 2. The Prism (Floating Command Bar - Cmd+K)
  • 3. The Aura (Ghost Text Autocomplete)
  • 4. The Calibration Engine (Hardware Telemetry)
  • 5. The Context Engine (Local RAG)
  • 6. The Diff Engine (Selective Merging)
  • 7. The Autonomous Loop (Self-Healing Tests)
• System Architecture
• Hardware Calibration & Model Matrix
• Prerequisites
• Installation & Setup
• Quickstart Guide
• Configuration Reference
• Keyboard Shortcuts & Commands
• Repository Structure
• Development & Testing
• Troubleshooting & FAQ
• Contributing
• License

🌟 Executive Summary

Lumina is a professional-grade, privacy-first VS Code extension designed to transform your editor into an autonomous AI coding environment powered entirely by local models via Ollama.

Unlike conventional AI plugins that act as simple cloud-dependent chatbots, Lumina functions as an autonomous agent:

• It scans your physical system hardware (Apple Silicon Metal Unified Memory, NVIDIA CUDA, System RAM) to auto-tune parameters and eliminate system stutter.
• It indexes your entire local workspace into a local vector database for deep cross-file comprehension.
• It writes, refactors, tests, and merges code diffs directly within your source files with fine-grained developer approval.

🔒 Zero-Leak Data Sovereignty

Your codebase is your intellectual property. Lumina is engineered from the ground up on three strict privacy axioms:

1. Air-Gapped Operation: All inference, embeddings, and context retrieval occur locally via http://localhost:11434. No external API calls are made.
2. Zero Telemetry: No user prompts, file paths, keystrokes, or code snippets are transmitted to external servers.
3. User-Controlled Agency: Lumina never writes to your files without an explicit user trigger or approval via the Diff Review Engine.

✨ Key Features

1. The Nexus (Glassmorphic Sidebar)

The central intelligence hub embedded directly in the VS Code Activity Bar (lumina.nexusView):

• Obsidian Glassmorphic UI: Deep frosted acrylic containers (backdrop-filter: blur(16px)), responsive micro-animations, and vibrant glowing status indicators.
• Context Chips Hub: Real-time visual tags for active files and pinned context folders. Drag, drop, or click to toggle files in the AI's short-term memory.
• Dynamic Model Switcher & Puller: Switch between active local models on the fly and monitor running processes in VRAM.
• Interactive Markdown Streamer: Real-time streaming token renderer with syntax highlighting, 1-click Copy, Apply to Editor, and Diff & Review controls.

2. The Prism (Floating Command Bar - Cmd+K / Ctrl+K)

A lightweight, modal command bar for targeted in-place code transformations:

• Highlight any code block (or whole document) and press Cmd+K (macOS) or Ctrl+K (Windows/Linux).
• Choose from preset actions (Refactor Selection, Generate Unit Tests, Fix Diagnostics, Add Strict Types, Optimize Performance) or type a custom natural language instruction.
• Automatically launches a side-by-side diff comparison view for review.

3. The Aura (Ghost Text Autocomplete)

Low-latency inline code autocomplete powered by Fill-In-The-Middle (FIM) prompt engineering:

• Context-aware suggestions appear in grayed-out ghost text as you type.
• Press Tab to accept full completion.
• Built-in adaptive debouncing and cancellation token management to preserve local inference resources.

4. The Calibration Engine (Hardware Telemetry)

Hardware-aware intelligence that prevents system crashes:

• Queries OS hardware: CPU cores, total/free RAM, GPU architecture, Apple Metal unified memory, and NVIDIA VRAM.
• Automatically classifies host capacity into Low, Balanced, or Power profile tiers.
• Integrated TPS Benchmark Runner: Measures tokens-per-second and time-to-first-token (TTFT) against your active Ollama model.

5. The Context Engine (Local RAG)

Local semantic retrieval across your entire repository:

• Non-blocking workspace scanner that respects .gitignore and ignores binary assets / build directories.
• Sliding window code chunker with file path, language, and line range annotations.
• Zero-dependency local vector store utilizing Cosine Similarity with disk caching (.lumina/vector_cache.json).

6. The Diff Engine (Selective Merging)

Full developer control over code modifications:

• High-precision Myers/LCS diff algorithm producing structured line-by-line hunks.
• Opens side-by-side comparison view using native VS Code diffing (lumina-diff://).
• Granular Actions:
  • Accept All: Merges all proposed hunks atomically.
  • Selective Accept: Merge individual hunks or lines.
  • Reject: Discards the proposal with zero filesystem trace.

7. The Autonomous Loop (Self-Healing Tests)

An iterative agent workflow for continuous bug fixes:

1. Executes your local test runner or compiler (e.g. npm test, pytest, cargo test, tsc).
2. Captures stdout/stderr and error stack traces.
3. Diagnoses the root failure cause with Ollama.
4. Synthesizes a patch and applies it to source code.
5. Re-runs the test suite to verify resolution.

📐 System Architecture

flowchart TB
    subgraph UI ["Layer 1: Developer Interface"]
        Aura["The Aura (Ghost Text)"]
        Prism["The Prism (Cmd+K Modal)"]
        Nexus["The Nexus (Glassmorphic Sidebar)"]
    end

    subgraph Core ["Layer 2: Sovereign Orchestrator"]
        PromptBuilder["Prompt Builder & Memory"]
        AutoLoop["Autonomous Test Loop"]
        DiffEngine["Myers Diff Engine"]
    end

    subgraph Context ["Layer 3: Local Context Engine"]
        Crawler["Workspace Crawler"]
        Chunker["Sliding Window Chunker"]
        VectorStore["Local Vector Store (Cosine Sim)"]
        Chips["Context Chips Hub"]
    end

    subgraph Inference ["Layer 4: Local AI Engine"]
        Bridge["Ollama REST Bridge"]
        Calib["Hardware Calibration & Telemetry"]
        OllamaServer[("Local Ollama Server\nhttp://localhost:11434")]
    end

    UI --> Core
    Core --> Context
    Core --> Inference
    Inference --> OllamaServer
    DiffEngine --> UI

💻 Hardware Calibration & Model Matrix

Lumina intelligently maps your detected hardware to recommended local open-source models:

📦 Prerequisites

1. VS Code: Version 1.80.0 or later.
2. Node.js: Version 18.0.0 or later (Node v20+ recommended).
3. Ollama: Installed and running locally.
   • Install from ollama.com
   • Verify server is active:

     curl http://localhost:11434/api/tags
     

🚀 Installation & How to Run

Method 1: Run Live in VS Code with F5 (Recommended for Development)

1. Install dependencies and build:

   npm install
   npm run build
   

2. Launch the Extension:

   • In VS Code, press F5 (or click Run $\rightarrow$ Start Debugging from the top menu).
   • This opens a new [Extension Development Host] VS Code window with Lumina loaded and active.

3. Verify it's Running:

   • In the new window, click the Lumina Sparkle icon in the left Activity Bar to open the Nexus Hub.
   • Open any code file, select a function, and press Cmd+K (macOS) or Ctrl+K (Windows/Linux) to trigger The Prism.
   • Type code to see The Aura ghost text autocomplete appear.

Method 2: Live Watch Mode (npm run dev)

If you are modifying TypeScript or webview code:

# Starts automatic build watcher
npm run dev
# (or)
npm start

Any changes you make to src/ will automatically recompile into dist/. In the Extension Development Host window, press Cmd+R (or Ctrl+R) to reload instantly.

Method 3: Install .vsix Directly into your Local VS Code

To install Lumina permanently into your main VS Code environment without running debug mode:

# 1. Package the extension
npm run package

# 2. Install into VS Code
code --install-extension lumina-ai-agent-0.1.1.vsix

⚡ Quickstart Guide

1. Pull Your Preferred Local Model

# Recommended for balanced setups:
ollama pull qwen2.5-coder:7b

# Recommended for local embeddings (RAG):
ollama pull nomic-embed-text

2. Launch Nexus & Calibrate

1. Click the Lumina Sparkle Icon in the VS Code Activity Bar.
2. Navigate to the Hardware tab and click Rescan Hardware.
3. Click Benchmark Model (TPS) to measure your local token generation speed.

3. Use Prism for Fast Code Editing

1. Select a block of code in any editor.
2. Press Cmd+K (macOS) or Ctrl+K (Windows/Linux).
3. Select an action (e.g. Refactor & Clean Code) or enter your prompt.
4. Review the generated changes in the side-by-side diff window and click Accept All or Reject.

4. Index Workspace for Deep Context (RAG)

1. In the Nexus sidebar, open the Context Hub tab.
2. Click Index Workspace Now.
3. All code files are indexed into your private local vector store.

⚙️ Configuration Reference

Customize Lumina through VS Code Settings (settings.json):

{
  // URL of your local Ollama server
  "lumina.ollamaEndpoint": "http://localhost:11434",

  // Selected primary coding model (e.g., qwen2.5-coder:7b, llama3.1:8b)
  "lumina.selectedModel": "qwen2.5-coder:7b",

  // Model used for vector embeddings
  "lumina.embeddingModel": "nomic-embed-text",

  // Enable/disable Aura Ghost Text inline autocomplete
  "lumina.enableGhostText": true,

  // Debounce delay in milliseconds for ghost text
  "lumina.ghostTextDelay": 350,

  // Sampling temperature for code generation (0.0 - 1.0)
  "lumina.temperature": 0.2,

  // Automatically scan hardware on startup
  "lumina.autoCalibrateOnStartup": true,

  // Maximum number of RAG chunks to inject into context
  "lumina.maxRagChunks": 5
}

⌨️ Keyboard Shortcuts & Commands

📂 Repository Structure

lumina/
├── .vscode/               # VS Code launch and task configs
├── resources/             # Extension icons and visual assets
│   └── lumina-icon.svg
├── src/
│   ├── aura/              # The Aura (Ghost Text inline completion)
│   │   └── inlineCompletion.ts
│   ├── calibration/       # Hardware Telemetry & Recommender
│   │   ├── telemetry.ts
│   │   ├── recommender.ts
│   │   └── benchmarker.ts
│   ├── diff/              # Myers Diff Engine & Comparison Provider
│   │   ├── diffEngine.ts
│   │   ├── diffProvider.ts
│   │   └── patchManager.ts
│   ├── nexus/             # The Nexus (Glassmorphic Sidebar Webview)
│   │   ├── nexusViewProvider.ts
│   │   └── media/
│   │       ├── nexus.html
│   │       ├── nexus.css
│   │       └── nexus.js
│   ├── ollama/            # Local Ollama REST Client & Manager
│   │   ├── client.ts
│   │   └── manager.ts
│   ├── orchestrator/      # Sovereign Orchestrator & Autonomous Loop
│   │   ├── promptBuilder.ts
│   │   ├── sovereignOrchestrator.ts
│   │   └── autonomousLoop.ts
│   ├── prism/             # The Prism (Cmd+K Floating Command Bar)
│   │   └── floatingCommandBar.ts
│   ├── rag/               # Local Context Engine & Vector Store
│   │   ├── crawler.ts
│   │   ├── chunker.ts
│   │   ├── vectorStore.ts
│   │   └── contextEngine.ts
│   ├── utils/             # OutputChannel logger & StatusBar
│   │   ├── logger.ts
│   │   └── statusBar.ts
│   ├── extension.ts       # Main extension activation entry point
│   └── types.ts           # Core TypeScript types & message protocols
├── test/
│   └── test-suite.js      # Unit and integration test suite
├── Documentation.md       # Original specification & whitepaper
├── esbuild.js             # Asset packaging pipeline
├── package.json           # Extension manifest & contribution points
├── tsconfig.json          # TypeScript compiler configuration
└── readme.md              # Project documentation

🛠️ Development & Testing

Building

# Typecheck TypeScript source
npm run typecheck

# Bundle extension with esbuild
npm run build

# Watch mode for active development
npm run build:watch

Running Tests

Lumina includes a standalone verification suite covering the Diff Engine, Code Chunker, Model Recommender, and Cosine Similarity math:

npm run compile
node test/test-suite.js

❓ Troubleshooting & FAQ

🤝 Contributing

Contributions are warmly welcomed! To contribute:

1. Fork the Repository on GitHub.
2. Create a Feature Branch: git checkout -b feature/amazing-feature
3. Commit Your Changes: git commit -m "feat: add amazing feature"
4. Push to the Branch: git push origin feature/amazing-feature
5. Open a Pull Request.

Please ensure all tests pass with node test/test-suite.js before submitting.

📄 License

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