🧠 LEVI // Private Local-First Windows AI Companion

A private, local-first Windows AI companion powered by an on-device llama.cpp server. Combines a conversational CLI, guarded desktop assistance, project generation, local screen OCR, and system diagnostic tooling without requiring cloud API keys.

Note

Development Note: This repository was published after the initial development phase. The GitHub commit history therefore does not represent the complete development timeline.

---

🖥️ Interactive CLI Preview

┌────────────────────────────────────────────────────────────────────────┐
│ LEVI v1.0 [Local Engine: llama.cpp @ 127.0.0.1:8080] │
│ │
│ > enter companion mode │
│ [GUARD] Companion Mode activated. Permissions scoped to this session. │
│ > window active │
│ [INFO] Active Window: Visual Studio Code - Devsync │
│ > screen ask What does this build error mean? │
│ [OCR] Extracting screen region... Text parsed. │
│ [LEVI] The error shows a missing alembic migration on table 'devices'.│
│ Run 'alembic upgrade head' to sync schema. │
└────────────────────────────────────────────────────────────────────────┘

---

🏗️ System Architecture

graph TD
User([User / Windows Hotkey]) --> CLI[LEVI Conversational CLI]
CLI --> Router{Intent Router & Guard}
Router -->|Inference| Llama[Local llama.cpp Server<br/>GGUF Model on 127.0.0.1:8080]
Router -->|Companion Mode| Perms[Session Capability Manager<br/>Explicit Session Grants]
Perms --> WinDiag[Windows Diagnostics<br/>CPU / RAM / Disk / Processes]
Perms --> ScreenOCR[Screen OCR Subsystem<br/>Tesseract Engine]
Perms --> WinControl[Windows Action Guard<br/>App Launcher / Media / Input]
Router -->|Code Scaffolding| ProjGen[Project Generator<br/>Design -> Preflight -> Validation -> Self-Repair]
Router -->|State & Context| SQLite[(SQLite Local Memory Store)]
classDef core fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff;
classDef comp fill:#0f172a,stroke:#10b981,stroke-width:1px,color:#fff;
class CLI,Router,Llama core;
class WinDiag,ScreenOCR,ProjGen,SQLite comp;

Loading

---

✨ Key Features

• 100% Local Inference: Communicates with any OpenAI-compatible local llama.cpp server running open-weight GGUF models. Your data never leaves your hardware.
• Companion Mode with Guarded Permissions: Session-scoped granular grants for window inspection, screen capture, keyboard/mouse controls, and application launching.
• Autonomous Project Scaffolding: End-to-end project generator that handles system architecture, file scaffolding, preflight syntax validation, test execution, and bounded automatic self-repair.
• Local Screen OCR: Query on-screen content instantly via screen read and screen ask <question> using local Tesseract OCR.
• Windows System Diagnostics: On-demand health audits for CPU loads, memory saturation, disk volumes, network interfaces, pending updates, and active processes.
• Persistent Conversation Memory: SQLite-backed conversational persistence allowing session resumption across restarts.

---

⚡ Quick Start

1. Clone & Set Up Environment

git clone https://github.com/Krishagarwal558/LEVI.git
cd LEVI
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item config\settings.example.json config\settings.json

2. Start your Local llama.cpp Server

llama-server -m <path-to-model.gguf>--host 127.0.0.1--port 8080

3. Launch LEVI

python main.py

---

🛡️ Companion Mode & Permission Model

Companion capabilities are disabled by default and all authorizations expire immediately when the current session terminates:

enter companion mode
allow windows session
window active
allow screen once
screen read
screen ask What does this error mean?

• System commands like open notepad require a secondary explicit confirm prompt.
• Use stop, revoke all, or exit companion mode at any time to purge all granted privileges instantly.

---

🧪 Running Tests

python -m pytest -q

---

🔒 Privacy and Safety

• Local databases, generated projects, application settings, screenshots, and logs are strictly ignored in .gitignore.
• Companion Mode never grants screen, keyboard, or file modification privileges automatically.
• Path traversal and unauthorized filesystem manipulation are prevented via preflight path sandboxing.
• Never commit config/settings.json; keep all machine-specific paths in your untracked local environment.

---

📄 License

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