.---.
     /     \
    | () () |   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 (+25 XP), running commands (+25 XP), asking questions (+10 XP).
  • Unlocks evolutions and visual accessories (Cyberpunk Visor, Magic Spellbook, Golden Crown).

9. 🎨 Casper Wardrobe (Visual Themes & Skins)

• Launch Casper in distinct aesthetic themes designed for dark mode and modern workstations:
  • 💎 glass: Default translucent Apple porcelain moonlight aesthetic.
  • ⚡ cyberpunk: Vibrant neon cyan body with radioactive magenta aura.
  • 👑 gold: Radiant royal gold aura and drop-shadows.
  • 🟢 matrix: Terminal hacker phosphor-green glow.
• CLI: ghost pet --skin cyberpunk or switch with 1 click from the Menu Bar!

10. 🍕 Casper Feeder (Physical Drag-and-Drop Ingestion)

• Drag & drop any code file (.py, .js, .ts, .json), log, or PDF directly onto Casper.
• Triggers interactive chewing wobble animation (@keyframes ghostChewWobble) and cheerful thought bubbles.
• Ingests files into Zero-DB RAG without opening complex upload modals.

11. 👻 Native macOS Menu Bar Controller

• Lightweight native NSStatusBar menu bar icon living right in your macOS status bar (ghost bar or ghost pet --tray).
• 1-click Casper toggle, wardrobe skin switcher, model selector, and instant VRAM flush with 0 KB background bloat.

12. 🔍 Instant Spotlight HUD

• Fast, centered floating command bar (ghost spot) for instant distraction-free questions and terminal autopilot commands. Press Esc to instantly dismiss.

13. 🤖 Local Model & Hardware Acceleration Catalog

• Scans local Ollama backends, detects downloaded models with footprints in GB, identifies hardware tier (Apple Silicon Metal MPS, NVIDIA CUDA, or CPU), and suggests lightweight models for 4GB–8GB RAM setups (ghost models).

14. 💎 Apple Glassmorphism HUD & 1-Click Code Blocks (v1.3.0)

• Unified 4-Tab Navigation: Consolidated 9 cluttered tabs into 4 streamlined workspaces: 💬 Chat, 📚 Knowledge (RAG), 🛠️ OS Tools (with sub-tools: OS Agent, Screen Peek, Clipboard Inspector, Safe Terminal Autopilot, Standup Journal), and 🧠 VRAM.
• Live Wardrobe Skin Switcher: Toggle between Glass, Cyberpunk, Gold, and Matrix themes directly from the header dropdown with instant persistence.
• Quick Action Suggestion Chips: 1-tap chips (👋 What can you do?, 🌤️ Weather in Almaty, 📂 Open Downloads, 📸 Screen Peek, 📋 Inspect Clipboard) for instant productivity.
• Syntax Code Blocks with 1-Click Copy: Beautiful dark syntax blocks featuring language badges and 1-click clipboard copy buttons.
• Universal Fullscreen Drag-and-Drop: Drag any file onto Casper or anywhere onto the HUD dropzone to train local Zero-DB RAG in milliseconds (+25 XP!).
• Native Apple Retina Dock Icon: Bundles official Apple Retina .icns artwork into macOS Dock, Application switcher, and /Applications/GhostOS.app.

📊 Why GhostOS vs. Others?

🚀 Quickstart

1. Instant Installation

macOS & Linux (One-line terminal installer):

curl -fsSL https://raw.githubusercontent.com/GhostOS-ai/GhostOS/main/install.sh | bash

(On macOS, this automatically sets up /Applications/GhostOS.app with Casper's native Retina icon in Launchpad and Spotlight).

Or install via Python pip:

pip install --upgrade ghostos-ai

2. Launch Casper Desktop Pet & HUD

ghost pet

Or on macOS: launch GhostOS directly from Spotlight (Cmd + Space), Launchpad, or double-click /Applications/GhostOS.app!

3. Or use directly from Terminal (CLI)

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

# Launch Casper Desktop Pet (with wardrobe skins & native menu bar)
ghost pet --skin cyberpunk --tray

# Launch centered Spotlight HUD
ghost spot

# Launch native macOS Menu Bar controller
ghost bar

# Inspect local models & hardware acceleration
ghost models

# 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.