.---.
     /     \
    | () () |   G H O S T O S
     \  -  /    The Invisible, Featherweight, Offline Desktop AI Copilot
    /`---'\
   /       \    [ 100% Private • Dynamic VRAM Juggler • Zero-DB RAG • Casper Pet ]
  (_/^\_/\_/^)

💡 Why GhostOS?

Running local AI today is frustrating and bloated:

• Electron RAM Bloat: Most local AI desktop apps (LM Studio, Jan, AnythingLLM) burn 800MB–1.2GB of RAM on the UI alone before a single neural weight is loaded into memory.
• The Multi-Model OOM Trap: Trying to run an LLM (3GB) + Vision model (2GB) + Whisper (1GB) simultaneously crashes any device with 4GB–8GB RAM.
• Overcomplicated RAG Stacks: Document chat tools force users to install Docker containers, heavy vector databases (Chroma/Qdrant), and gigabytes of bloated Python dependencies.

GhostOS solves this from first principles:

1. Casper Companion Pet & HUD: Rendered via native system web engines (WebKit on macOS, Edge WebView2 on Windows, WebKitGTK on Linux) consuming just ~35MB RAM.
2. Dynamic VRAM Juggler: Dynamically hot-swaps between LLM, Vision, and Whisper on demand in <150ms. Peak VRAM never exceeds 3.5GB.
3. Zero-DB RAG: Drop files onto Casper — indexed in milliseconds using pure SQLite FTS5 with zero external database dependencies.
4. 100% Local & Private: Zero telemetries, zero cloud fallbacks. Fully functional air-gapped with Wi-Fi switched off.

✨ Exclusive Killer Features

1. 👻 Casper: The Living Desktop Pet

• A quiet, translucent porcelain ghost that floats gently over your workspace.
• "Casper Eats Files": Drag & drop any PDF, code repository, notes, or spreadsheet directly onto Casper. Casper opens his mouth, swallows the file, and indexes it into your local knowledge base instantly (+15 XP!).
• Visual Moods & Reactive States:
  • 💤 Idle: Weightless floating animation, 0% CPU footprint.
  • 🔮 Thinking: Ethereal sapphire aura, streaming local neural tokens.
  • 🎧 Listening: Casper wears glowing headphones, capturing offline meetings.
  • 🍕 Eating: Document suction animation with real-time XP gain.
  • ⚠️ Alarm: Visual security warning when a dangerous shell command is detected.
• Single-click for quick phrases & interactions; double-click or press Cmd+Shift+Space / Ctrl+Shift+Space to morph into the Spotlight HUD.

2. ✍️ Ghostwriter (AI Inline Completion in Any App)

• Highlight text anywhere (Word, Telegram, browser, IDE, terminal) $\rightarrow$ press hotkey $\rightarrow$ transform instantly:
  • ✨ polish: Professional, crisp, and concise rewrite.
  • 🤝 polite: Diplomatic, respectful business tone.
  • 📝 grammar: Fixes spelling and grammar mistakes with zero conversational fluff.
  • 🎯 summarize: Distills text down to 2-3 key takeaways.
  • 🌐 translate: Instant translation into English, Russian, Kazakh, Chinese, etc.
  • 🛠️ code_fix: Automatically diagnoses and fixes bugs in code snippets.
• Use from CLI: ghost write --mode polite "draft message" or rewrite clipboard in 1 click!

3. 🧠 Memory Vault (Cross-Session Context Graph)

• Local SQLite knowledge graph that permanently stores personal context across restarts.
• Casper automatically remembers your developer stack, favorite languages, and active projects.
• Injects personal context into queries with 0 KB extra VRAM and 0% background CPU footprint.
• CLI: ghost vault list, ghost vault remember tech_stack "Python, Rust, Apple Silicon".

4. 🛡️ Terminal Sandbox Lens (Destructive Command Protection)

• Deep safety inspection for shell commands before execution.
• Intercepts and blocks destructive operations (rm -rf /, mkfs, raw dd, DROP DATABASE, format C:).
• Explains risks in plain human language and suggests safe alternatives before running.
• Interactive audit: ghost sandbox "rm -rf /".

5. 📅 Daily Standup & Conventional Commit Crafter

• Analyzes daily workspace file modifications, git diffs, and session commits.
• Generates ready-to-share Daily Standup reports for Slack / Telegram ("What I accomplished", "What I'm working on", "Blockers").
• Automatically crafts semantic Conventional Commits (feat(...), fix(...), refactor(...)).
• CLI: ghost standup.

6. 🎙️ Auto-Minutes Meeting Copilot

• 100% private offline secretary for Zoom, Google Meet, and voice notes.
• Generates structured markdown meeting minutes with Executive Overview, Key Decisions, and Action Items with Deadlines.
• Whisper model hot-swaps in only for the 5-second transcription window and immediately frees VRAM.

7. 🦎 Memory Chameleon (Adaptive Power Profiles)

• Dynamically monitors battery state and system RAM pressure:
  • 🍃 ECO Mode: Triggers on battery or RAM > 82%. Context capped at 1024 tokens, 2 CPU threads, 60s auto-sleep, 30 FPS pet.
  • ⚖️ Balanced Mode: Context 2048 tokens, 4 threads, 180s auto-sleep.
  • ⚡ Performance Beast: On AC power and free RAM > 50%. Context 4096 tokens, full GPU acceleration.

8. 🎮 Casper RPG Evolution System

• Gamified companion that grows with your work:
  • Gain XP for feeding files (+15 XP), running commands (+25 XP), asking questions (+10 XP).
  • Unlocks evolutions and visual accessories (Cyberpunk Visor, Magic Spellbook, Golden Crown).

📊 Why GhostOS vs. Others?

🚀 Quickstart

1. Clone & Install

git clone https://github.com/GhostOS-ai/GhostOS.git
cd GhostOS
pip install -e .

2. Launch Casper Desktop Pet & HUD

ghost pet

Casper will float on your desktop. Drag any file onto him, or click him to open the HUD!

3. Or use directly from Terminal (CLI)

# Instant question with zero setup
ghost "Why does Python raise RecursionError and how to fix it?"

# Feed a document or source directory to Casper (Zero-DB RAG)
ghost eat ~/Documents/my_notes.txt
ghost eat ./src/

# Inline AI Ghostwriter (rewrites clipboard or given text)
ghost write --mode polite "can you fix this asap"
ghost write --mode grammar

# Long-term Memory Vault
ghost vault remember tech_stack "Python, Rust, Apple Silicon"
ghost vault list

# Daily Standup Report & Semantic Commit Crafter
ghost standup

# Terminal Sandbox Safety Lens
ghost sandbox "rm -rf /"

# Search indexed knowledge
ghost rag search "database migration"

# Inspect current active screen
ghost screen

# Generate and safely run a terminal task
ghost exec "find all files larger than 100MB"

# Check VRAM Juggler memory diagnostics
ghost status

⌨️ Keyboard Shortcuts

🏗️ Architecture

flowchart TD
    User([User Desktop]) -->|Drag & Drop File / Click| Pet["👻 Casper Floating Pet (Native Engine)"]
    User -->|Hotkey Cmd+Shift+Space| HUD["🔮 Spotlight HUD / Command Bar"]
    User -->|Terminal CLI| CLI["💻 ghost CLI (rich)"]

    Pet --> Bridge["Python <-> JS Bridge API"]
    HUD --> Bridge
    CLI --> Core["GhostOS Core Engine"]
    Bridge --> Core

    subgraph MemoryManagement ["🧠 VRAM Juggler & Memory Chameleon"]
        Core --> Juggler["Memory Juggler Dispatcher"]
        Juggler -->|Hot-Swap <= 3.5GB| M1["Qwen 2.5 / Llama 3.2 (LLM)"]
        Juggler -->|Hot-Swap <= 2.0GB| M2["Moondream2 / MiniCPM (Vision)"]
        Juggler -->|Hot-Swap <= 0.6GB| M3["Whisper (Voice Copilot)"]
    end

    subgraph Storage ["📂 Zero-DB Storage & Vault"]
        Core --> RAG["SQLite FTS5 Knowledge Base"]
        Core --> Vault["🧠 Memory Vault (Long-Term Facts)"]
        RAG --> Docs[("Local Notes / Code / PDFs")]
    end

    subgraph OSIntegration ["⚡ System Integration"]
        Core --> Screen["Silent Screen Inspector"]
        Core --> Pilot["Safe Terminal Autopilot"]
        Core --> Lens["🛡️ Sandbox Lens"]
        Core --> Writer["✍️ Ghostwriter Engine"]
    end

🔒 100% Paranoid Privacy Pledge

GhostOS is engineered with privacy as a foundational constraint:

• Zero Telemetry: No analytics, no phone-home pings, no user tracking.
• Zero Cloud Fallbacks: Every neural calculation runs locally on your device's CPU/GPU.
• Air-Gapped Ready: Works with your Wi-Fi completely disabled.

🤝 Contributing

Contributions are warmly welcomed! Feel free to submit issues, pull requests, or custom Casper skins.

# Run full unit test suite (44+ tests)
python3 -m unittest discover tests

📄 License & Authorship

• Author: KIB.best
• Email: GhostOS@kib.best
• License: MIT License © 2026 KIB.best. Free for personal and commercial use.