Content
<div align="center">
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- HERO HEADER -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<img src="assets/icons/CubicLM.png" alt="CubicLM" width="190" />
## CubicLM
Computational Universe for Building Intelligent Learning Machines
### The Cross-Platform AI Chat Powerhouse
**Run LLMs locally on your Android device** via GPU-accelerated **llama.cpp** 🦙 & Google's **LiteRT-LM** ⚡<br/>
**Connect to 23+ cloud providers** ☁️ · **Extend with Skills** 🧩 · **Built-in OpenAI-compatible API** 🔌
<br/>
[](https://github.com/abir2afridi/CubicLM/releases/tag/v1.16.0)
[](https://github.com/abir2afridi/CubicLM/releases)
[](https://github.com/abir2afridi/CubicLM/stargazers)
[](https://github.com/abir2afridi/CubicLM/network/members)
<br/>
[](https://github.com/abir2afridi/CubicLM/releases/tag/v1.16.0)
[](https://github.com/abir2afridi/CubicLM/releases/tag/v1.16.0)
[](#-universal-multi-platform)
[](https://cubiclm.vercel.app)
<br/>
<!-- Tech Stack Pills -->
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Flutter-3.x-02569B?style=flat-square&logo=flutter&logoColor=white" alt="Flutter"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Dart-0175C2?style=flat-square&logo=dart&logoColor=white" alt="Dart"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white" alt="Kotlin"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/C++-00599C?style=flat-square&logo=cplusplus&logoColor=white" alt="C++"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/GetX-8A2BE2?style=flat-square" alt="GetX"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Hive-FFA000?style=flat-square" alt="Hive"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Firebase-FFCA28?style=flat-square&logo=firebase&logoColor=black" alt="Firebase"/></a>
<a href="#-license"><img src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square" alt="License"/></a>
<br/>
<!-- Stats Row -->
<table>
<tr>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/23%2B-Cloud%20Providers-FF4D00?style=flat-square" alt="23+ Providers"/>
<br/><sub><b>Cloud AI</b></sub>
</td>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/15-Languages-8b5cf6?style=flat-square" alt="15 Languages"/>
<br/><sub><b>Localization</b></sub>
</td>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/18%2B-Bundled%20Models-22c55e?style=flat-square" alt="18+ Models"/>
<br/><sub><b>On-Device</b></sub>
</td>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/5-Starter%20Skills-3b82f6?style=flat-square" alt="5 Skills"/>
<br/><sub><b>Extensions</b></sub>
</td>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/3-Supported%20Shells-facc15?style=flat-square" alt="3 Shells"/>
<br/><sub><b>Multi-Platform</b></sub>
</td>
<td align="center" width="16.66%">
<img src="https://img.shields.io/badge/100%25-Offline%20Ready-0ea5e9?style=flat-square" alt="Offline"/>
<br/><sub><b>Privacy First</b></sub>
</td>
</tr>
</table>
<br/>
> 📱⚡ A cross-platform AI chat application with local on-device inference and multi-provider cloud AI support. Runs LLMs directly on your Android device via GPU-accelerated **llama.cpp** 🦙 and Google's **LiteRT-LM** runtime ⚡, with an optional built-in OpenAI-compatible API server 🔌.
<br/>
[**📥 Download**](#-download--v1160) · [**✨ Features**](#-features) · [**🤖 Models**](#-supported-models) · [**🛠️ Stack**](#-tech-stack) · [**📂 Structure**](#-project-structure) · [**🚀 Setup**](#-getting-started) · [**⚙️ Config**](#️-configuration) · [**❓ FAQ**](#-frequently-asked-questions) · [**🤝 Contribute**](#-contributing)
</div>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- WHAT IS CUBICLM? -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/target/target2.gif" width="90" />
## What is CubicLM?
</div>
<table>
<tr>
<td width="50%" valign="top">
### 💡 The Idea
**CubicLM** is a *single Flutter codebase* that ships as a **native Android app**, a **Windows desktop app**, and (soon) a **web app** — with zero feature forks. Whether you're running a 16B MoE model on your phone's GPU, streaming tokens from GPT-5.2, or spinning up a local OpenAI-compatible API server for your homelab, it's all the *same `lib/` directory*.
**No cloud lock-in. No telemetry by default. No dark patterns.** Just a clean, warm, Claude-inspired chat interface that respects your device, your data, and your time.
</td>
<td width="50%" valign="top">
### 🎁 What You Get
- 🔒 **Full offline capability** — download a model once, chat forever without internet
- ⚡ **GPU acceleration** — Vulkan / OpenCL on Android for real-time token streaming
- ☁️ **23+ cloud providers** — swap between OpenAI, Anthropic, Gemini, Groq, or any OpenAI-compatible endpoint
- 🧩 **Extensible** — Skills for prompt injection, MCP for live tools
- 🔌 **Built-in API server** — turn your phone into an OpenAI-compatible endpoint on port `8080`
- 🎨 **Beautiful UI** — warm Claude-inspired palette, thinking orbs, streaming markdown
- 🌍 **15 languages** — EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR
</td>
</tr>
</table>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- DOWNLOAD -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/download/installing-updates.gif" width="80" />
## Download — `v1.16.0`
> 🎉 **Latest release** · Build date: current · [View full changelog →](CHANGELOG.md)
</div>
<table>
<thead>
<tr>
<th align="center" width="40">Platform</th>
<th align="left">Architecture</th>
<th align="left">File</th>
<th align="right">Size</th>
<th align="center">Download</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>arm64-v8a · modern phones</sub></td>
<td><code>cubiclm-v1.16.0-arm64-v8a.apk</code></td>
<td align="right"><b>67 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.16.0/cubiclm-v1.16.0-arm64-v8a.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>armeabi-v7a · older devices</sub></td>
<td><code>cubiclm-v1.16.0-armeabi-v7a.apk</code></td>
<td align="right"><b>21 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.16.0/cubiclm-v1.16.0-armeabi-v7a.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>x86_64 · emulators, tablets</sub></td>
<td><code>cubiclm-v1.16.0-x86_64.apk</code></td>
<td align="right"><b>32 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.16.0/cubiclm-v1.16.0-x86_64.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/windows/windows%20(2).png" width="120" /></td>
<td><b>Windows</b><br/><sub>x64 · requires WebView2</sub></td>
<td><code>cubiclm-v1.15.1-windows-x64.zip</code><br/><sub>unzip & run <code>cubiclm.exe</code></sub></td>
<td align="right"><b>17 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.15.1/cubiclm-v1.15.1-windows-x64.zip"><img src="https://img.shields.io/badge/⬇_GET-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/lock.png" width="120" /></td>
<td><b>Checksums</b><br/><sub>SHA-256 verification</sub></td>
<td><code>checksums.sha256</code></td>
<td align="right">—</td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.16.0/checksums.sha256"><img src="https://img.shields.io/badge/⬇_VERIFY-6b7280?style=for-the-badge&logo=shield&logoColor=white" alt="Verify"/></a></td>
</tr>
</tbody>
</table>
### 🧭 Which Build Should I Choose?
| Your Device | Recommended | Why |
| :--- | :--- | :--- |
| 📱 Modern Android phone (2020+) | **arm64-v8a** | Best performance, full GPU acceleration, all models run |
| 📱 Older / budget Android | **armeabi-v7a** | Smaller install, runs smaller quantized models |
| 🖥️ Android emulator / Chromebook | **x86_64** | Native architecture for Intel/AMD chips |
| 💻 Windows 10/11 PC | **windows-x64** | Cloud mode + Skills + MCP; optional local GGUF via llama-server sidecar when bundled (LiteRT/SD remain Android-first) |
| 🌐 Any browser | *Coming soon* | Web is `dart:ffi`-blocked; tracked for future release |
> [!NOTE]
> **🌐 Website:** [cubiclm.vercel.app](https://cubiclm.vercel.app) — landing page + direct APK / Windows downloads
> **📝 Full release notes:** [CHANGELOG.md](CHANGELOG.md) · [GitHub Release page](https://github.com/abir2afridi/CubicLM/releases/tag/v1.16.0)
> **ℹ️ Platform status:** Web (`dart:ffi`-blocked) is tracked for a future release — **Android + Windows** are the supported targets for `v1.12.0`.
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- TABLE OF CONTENTS -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
<div align="center">
<br/>
<!-- ═══════════════════════════════════════════════════════════════════ -->
<!-- ░░ SECTION HEADER ░░ -->
<!-- ═══════════════════════════════════════════════════════════════════ -->
<img src="https://img.shields.io/badge/📚-DOCUMENTATION%20MAP-FF4D00?style=for-the-badge&labelColor=0d1117&logo=readthedocs&logoColor=white" alt="Docs"/>
<h2>🧭 Navigation</h2>
**<sub>Everything you need — organized into <b>3 zones</b> · <b>23 sections</b> · <b>instant jump</b></sub>**
<br/>
<!-- ─── Quick Jump Bar ─── -->
<a href="#-what-is-cubiclm"><img src="https://img.shields.io/badge/🎯_Intro-FF4D00?style=flat-square&labelColor=0d1117" alt="Intro"/></a>
<a href="#-download--v1160"><img src="https://img.shields.io/badge/📥_Download-FF4D00?style=flat-square&labelColor=0d1117" alt="Download"/></a>
<a href="#-features"><img src="https://img.shields.io/badge/✨_Features-8b5cf6?style=flat-square&labelColor=0d1117" alt="Features"/></a>
<a href="#-supported-models"><img src="https://img.shields.io/badge/🤖_Models-22c55e?style=flat-square&labelColor=0d1117" alt="Models"/></a>
<a href="#-getting-started"><img src="https://img.shields.io/badge/🚀_Setup-3b82f6?style=flat-square&labelColor=0d1117" alt="Setup"/></a>
<a href="#-frequently-asked-questions"><img src="https://img.shields.io/badge/❓_FAQ-facc15?style=flat-square&labelColor=0d1117" alt="FAQ"/></a>
<br/>
---
## 🗂️ Documentation Zones
<table width="100%">
<tbody>
<tr>
<td width="33.33%" valign="top" align="center">
<img src="https://img.shields.io/badge/●_ZONE_1-CORE-FF4D00?style=for-the-badge&labelColor=0d1117" alt="Core"/>
<sub><b>🎯 Start here · Features · Models</b></sub>
<br/>
---
**🎯 Introduction**
*Get to know CubicLM*
🎯 [What is CubicLM?](#-what-is-cubiclm)
📥 [Download — v1.12.0](#-download--v1160)
---
**✨ Core Features**
*What makes it powerful*
🧠 [Local AI Inference](#-local-ai-inference)
🎛️ [Inference Parameters](#️-inference-parameters-settings--parameters)
🚀 [Startup & Onboarding](#-startup-onboarding--splash)
🌐 [Web Access](#-web-access-independent-chat)
🧠 [Chat Context Memory](#-chat-context-memory-follow-ups-dont-get-lost)
☁️ [Cloud Providers](#️-cloud-ai-providers)
---
**🤖 Model Catalog**
*18+ ready-to-run models*
⚡ [LiteRT-LM Models](#-supported-models)
🐫 [GGUF Models](#-supported-models)
🎨 [Image Generation](#-supported-models)
📊 [Selection Guide](#-supported-models)
<br/>
<img src="https://img.shields.io/badge/📍_START_HERE-1_→_2_→_3-FF4D00?style=for-the-badge&labelColor=0d1117" alt="Start"/>
</td>
<td width="33.33%" valign="top" align="center">
<img src="https://img.shields.io/badge/●_ZONE_2-EXTENSIONS-8b5cf6?style=for-the-badge&labelColor=0d1117" alt="Extensions"/>
<sub><b>🧩 Power features · Integrations</b></sub>
<br/>
---
**🧩 Extend & Integrate**
*Add new capabilities*
🧩 [Skills System](#-skills--offline-instruction-extensions)
🔌 [MCP Server](#-custom-mcp-server--single-remote-connection-no-marketplace)
🔌 [Built-in API](#-built-in-openai-compatible-api-server)
---
**🌐 Build & Deploy**
*Create & ship apps*
🌐 [CubicWeb Builder](#-cubicweb-builder-toolkit--v1120)
🖥️ [Multi-Platform](#️-universal-multi-platform--one-codebase-three-shells)
🔄 [Model Switcher](#-universal-multi-platform--one-codebase-three-shells)
---
**🩺 Monitor & Design**
*Debug & beautify*
🩺 [System Diagnostics](#-system-diagnostics-settings--config--system-logs)
🎨 [Theming & UX](#-theming--ux-deep-dive)
🔮 [Thinking Orbs](#-theming--ux-deep-dive)
<br/>
<img src="https://img.shields.io/badge/⚡_POWER_USER-Advanced_Features-8b5cf6?style=for-the-badge&labelColor=0d1117" alt="Power"/>
</td>
<td width="33.33%" valign="top" align="center">
<img src="https://img.shields.io/badge/●_ZONE_3-REFERENCE-3b82f6?style=for-the-badge&labelColor=0d1117" alt="Reference"/>
<sub><b>📖 Docs · Setup · Community</b></sub>
<br/>
---
**🛠️ Technical Docs**
*Under the hood*
🛠️ [Tech Stack](#-tech-stack)
📂 [Project Structure](#-project-structure)
📋 [Requirements](#-requirements)
---
**🚀 Build & Configure**
*From clone to release*
🚀 [Getting Started](#-getting-started)
⚙️ [Configuration](#️-configuration)
🔐 [Security & Privacy](#-security--privacy)
---
**💬 Help & Community**
*Support & contribution*
❓ [FAQ](#-frequently-asked-questions)
🐛 [Troubleshooting](#-troubleshooting)
🗺️ [Roadmap](#️-roadmap)
🤝 [Contributing](#-contributing)
💖 [Acknowledgments](#-acknowledgments)
📄 [License](#-license)
<br/>
<img src="https://img.shields.io/badge/📚_LEARN_MORE-Complete_Guides-3b82f6?style=for-the-badge&labelColor=0d1117" alt="Learn"/>
</td>
</tr>
</tbody>
</table>
## Choose Your Path
<sub><i>Pick the journey that matches your goal</i></sub>
<br/>
<table width="100%">
<tr>
<td width="25%" align="center" valign="top">
<h3>🆕</h3>
**First Time Here?**
<sub>Get up and running in 5 minutes</sub>
<br/>
<a href="#-download--v1160"><img src="https://img.shields.io/badge/📥_Download-FF4D00?style=for-the-badge" alt="Download"/></a>
<a href="#-getting-started"><img src="https://img.shields.io/badge/🚀_Setup-FF4D00?style=for-the-badge" alt="Setup"/></a>
<sub>1️⃣ Download → 2️⃣ Install → 3️⃣ Chat</sub>
</td>
<td width="25%" align="center" valign="top">
<h3>🔍</h3>
**Exploring Features?**
<sub>See what CubicLM can do</sub>
<br/>
<a href="#-features"><img src="https://img.shields.io/badge/✨_Features-8b5cf6?style=for-the-badge" alt="Features"/></a>
<a href="#-supported-models"><img src="https://img.shields.io/badge/🤖_Models-8b5cf6?style=for-the-badge" alt="Models"/></a>
<sub>Local · Cloud · Vision · Image</sub>
</td>
<td width="25%" align="center" valign="top">
<h3>⚡</h3>
**Power User?**
<sub>Extend with Skills & MCP</sub>
<br/>
<a href="#-skills--offline-instruction-extensions"><img src="https://img.shields.io/badge/🧩_Skills-8b5cf6?style=for-the-badge" alt="Skills"/></a>
<a href="#-custom-mcp-server--single-remote-connection-no-marketplace"><img src="https://img.shields.io/badge/🔌_MCP-8b5cf6?style=for-the-badge" alt="MCP"/></a>
<sub>Tools · Automation · APIs</sub>
</td>
<td width="25%" align="center" valign="top">
<h3>👨💻</h3>
**Developer?**
<sub>Build from source</sub>
<br/>
<a href="#-project-structure"><img src="https://img.shields.io/badge/📂_Structure-3b82f6?style=for-the-badge" alt="Structure"/></a>
<a href="#-contributing"><img src="https://img.shields.io/badge/🤝_Contribute-3b82f6?style=for-the-badge" alt="Contribute"/></a>
<sub>Fork · Build · PR</sub>
</td>
</tr>
</table>
</div>
</div>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- FEATURES -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# Features
<sub><i>Everything CubicLM can do — organized by capability</i></sub>
## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/ai/icons8-ai.gif" width="80" />
</div>
## 🧠 Local AI Inference
> **Your phone is the datacenter.** Download once, chat forever — no internet, no API keys, no rate limits.
<table>
<tr>
<td width="50%" valign="top">
### 🦙 llama.cpp Engine
- **LLM inference** via llama.cpp with **GGUF** models
- **GPU acceleration** — Vulkan / OpenCL backends
- **GPU crash recovery** — automatic CPU fallback if the GPU backend fails mid-generation
- **Custom Flutter plugin** (`local_plugins/llama_flutter_android`) with direct FFI bindings
### ⚡ Google LiteRT-LM
- **LiteRT-LM inference** via Google's runtime for `.litertlm` models
- **NPU-optimized** for modern Android SoCs
- **Custom Flutter plugin** (`local_plugins/flutter_litert_lm`)
### 🎨 Stable Diffusion 1.5
- **On-device image generation** from safetensors
- **Isolate-based processing** (`sd_isolate_processor.dart`) keeps the UI at 60fps
- **CPU / Vulkan / OpenCL** backend toggle with automatic model reload
</td>
<td width="50%" valign="top">
### 👁️ Vision Models
- **Qwen2-VL-2B** — image understanding
- **Gemma 4 E2B / E4B** — Google's multimodal Gemma
- Attach images from camera, gallery, or files
### 🎬 Streaming Generation
- **Real-time tokens-per-second** display
- Long answers stream as **plain text** (full markdown rendered on completion)
- **Adaptive flush** (150ms / 300ms) so the chat never janks during heavy generations
### 🔍 Device Intelligence
- **Auto-configuration** — context size & max tokens adapt to detected RAM tier
- **Device specification card** (`Settings → Config`) — brand, model, OS, CPU cores/ABI, RAM bar, display size, one-tap refresh
- **Real hardware identification** — reads `ro.soc.*` system properties to show the actual SoC (Snapdragon 8 Gen 2, Dimensity 9000, Tensor G3…) and probes Vulkan for the GPU renderer name (Adreno, Mali…)
- **SoC-aware quantization recommendations** based on the detected family
</td>
</tr>
</table>
---
### ⚙️ Device Intelligence
| Feature | Description |
| :--- | :--- |
| 🎚️ **Device-tier auto-configuration** | Adjusts context size and max tokens based on detected RAM |
| 📊 **Device specification card** | `Settings → Config` shows brand+model, OS version, CPU cores/ABI, RAM free-space bar, display size, one-tap refresh |
| 🔍 **Real hardware identification** | Reads `ro.soc.*` system properties to show the actual processor (Snapdragon 8 Gen 2, Dimensity 9000, Google Tensor G3…) and probes Vulkan for the GPU renderer name (Adreno, Mali…) instead of a generic "Unknown" label |
| 💡 **SoC-aware recommendations** | Quantization recommendations follow from the detected family |
---
## 🎛️ Inference Parameters *(Settings › Parameters)*
<table>
<tr>
<td width="50%" valign="top">
### 🪄 Auto Tune <sub>(default ON)</sub>
> One switch that keeps limits optimal for your device.
- ✅ Context window and output budget set to the **highest the device's RAM can safely run** (tier-based)
- ✅ Cloud requests sent **without an output cap** — large models write full detailed answers instead of stopping mid-response
- ✅ Inline **(i) info dialog** explains exactly what it does
### 🎚️ Manual Mode
> Flip Auto off for direct control with extended ranges.
| Parameter | Range |
| :--- | :--- |
| **Context window** | 1K → **1M tokens** (LiteRT capped to 4K by hardware) |
| **Output tokens** | 256 → **128K tokens** |
| **Warnings** | Orange warnings past device's recommended limit — but values stay selectable |
</td>
<td width="50%" valign="top">
### 📊 Full Parameter Reference
| Parameter | Behavior |
| :--- | :--- |
| 🌡️ **Inference temperature** | Applied on every generation, local and cloud |
| 🎯 **Local sampling** | Top-P / Top-K / repeat-penalty sliders (GGUF + LiteRT; cloud uses provider defaults) |
| 🔄 **Context window changes** | Auto-reload the resident model after the slider settles |
| 🎨 **Image generation** | Sampling steps and synthesis resolution (Auto mode scales by available RAM) |
| ⚡ **Compute backend** | CPU / Vulkan / OpenCL toggle with automatic model reload |
### 🛡️ RAM Guard *(new in v1.12.0)*
- `DeviceInfoService.canAllocateContextSize()` — computes `fileBytes + KV~2.5KB×context` vs 80% available RAM
- `SettingsController.setContextSize` clamps to `maxSafeContextSize` with snackbar
- `ModelController._confirmModelLoadSafety` includes KV estimate before showing *Restart recommended*
</td>
</tr>
</table>
---
## 🚀 Startup, Onboarding & Splash
<table>
<tr>
<td width="50%" valign="top">
### 🎬 Splash Screen
> No white flash, no jank, no waiting.
- **Warm native splash** — `launch_background` is `#F8F4ED` (matches `Dt.canvas`), `NormalTheme` matches — seamless native→Flutter transition
- **Animated CubicLM** — 44–48sp PlusJakartaSans w900
- Shimmer `LinearGradient` isolated in `RepaintBoundary`
- `760ms` fade-in/out · `1380ms` dwell → onboarding/home
- **No jank** after `runApp()` was moved to critical path
</td>
<td width="50%" valign="top">
### 👋 First-Run Onboarding *(new)*
`onboarding_view.dart` — 3-page `PageView`:
| Page | Topic | Icon |
| :---: | :--- | :---: |
| 1 | *Private by Default* | 🛡️ |
| 2 | *Or Use Any Cloud* (23+ providers) | ☁️ |
| 3 | *Pick Your First Model* (recommended chip) | 🎯 |
- Dots pagination + `Skip / Next / Start Chatting`
- Hive-persisted (`onboarding_done_v1`)
- i18n `onboarding_*` EN+BN, fallback for 13 langs
</td>
</tr>
</table>
### ⚙️ Initialization Strategy
<table>
<tr>
<td width="50%" valign="top">
**⏳ Deferred Heavy Init**
- `NotificationHistory / Skill / MCP / DeviceInfo / CrashReporting / ImageNotifications` start **`2200ms` after `runApp()`** (after splash completes)
- `Hive` per-box `3s` timeout with `_MemoryBox` fallback
- Result: native `launch_background` **never hangs**
</td>
<td width="50%" valign="top">
**🔄 Auto-Load Last Model** *(App Settings → STARTUP)*
Controlled by `AppConstants.keyAutoLoadLastModel`:
| Setting | Behavior |
| :---: | :--- |
| **`ON`** | After chat UI idle (splash gone + `DeviceInfo` ready + `1200ms`), checks `isModelLoaded` resident, `90s` crash-loop guard, `80%` RAM guard, then `loadModel().timeout(90s)` off the UI frame |
| **`OFF`** *(default)* | Shows `Resume Session?` dialog after `520ms` |
🛑 **Prevents** `mmap 2-7GB` during splash which previously froze 2nd open.
</td>
</tr>
</table>
---
## 🌐 Web Access *(independent chat)*
> The chat page can fetch live web content on its own — **no external services, no API keys, no third-party middlemen**.
<table>
<tr>
<td width="50%" valign="top">
### 🔧 How It Works
1. 🔘 Toggle the **🌐 button** in the chat input bar
2. 🔗 When on, any `https://…` links in your message are **downloaded automatically**
3. 🧹 Pages are stripped to **clean readable text** (scripts/styles removed, HTML entities decoded)
4. 🧠 Content injected into the model's context — works for **both local and cloud models**
</td>
<td width="50%" valign="top">
### 📏 Limits & Transparency
| Constraint | Value |
| :--- | :--- |
| Links per message | **3 max** |
| Characters per page | **~9K** |
| Timeout per fetch | **15s** |
| Source display | ✅ Tappable chips with **favicon** (Google S2) + domain + title |
| Failed fetches | ❌ Not shown, but logged |
</td>
</tr>
</table>
> [!TIP]
> No more "is web search working?" — you see exactly which sites were used, like ChatGPT/Claude, and can tap to open them. Great for **"summarize this article"**, **"what changed on this docs page"**, or grounding answers in real data.
---
## 🧠 Chat Context Memory *(follow-ups don't get lost)*
<table>
<tr>
<td width="50%" valign="top">
### 📦 History Storage
- **From storage, not the UI window** — every send rebuilds context from Hive
- Last **40 turns**, chronological
- The visible list is **paged** and never truncates what the model sees
### ✂️ Token-Budget Trim
| Scope | Budget |
| :--- | :--- |
| **Local** | ~60% of Context Size (~4 chars/token) |
| **Cloud** | 48K-char budget |
- Oversized single turns (e.g. a full HTML file) are **middle-truncated** — head + tail kept, `…middle trimmed…` marker
- Current + previous turn are **always kept** — so "make this better" still resolves to the code above it
</td>
<td width="50%" valign="top">
### 🛟 Safety Nets
- **UI fallback** — if storage ever returns empty while the chat shows turns, the visible list is used (with a warning in System Logs) instead of sending zero context silently
### 🧾 Proof in Logs
- Every send writes `Chat context: N turns, ~M tokens (user…user[, trimmed K])` to System Logs (Chat category)
- Roles + sizes only — **never content**
### 💡 Tip for Code Follow-Ups
- Long code answers eat context fast
- Use a **3B+ model** (or a strong cloud model)
- Raise **Settings › Parameters → Context Size** if the device allows
- Small 0.6B–1B models may still ask "which game?" on their own
</td>
</tr>
</table>
---
## 🧠 Long-Term Memory *(ROM, not RAM)*
> Chats persist in on-device Hive storage forever — but a 2K context window can't hold them. CubicLM auto-learns durable facts and recalls relevant past turns into each generation. 100% offline: no embeddings model, no online database.
| Layer | How |
| :--- | :--- |
| 📝 **Auto-learn facts** | "amar nam Abir" / "remember X" → fact box (EN + romanized Bangla patterns, max 2/turn, duplicates + contradictions auto-replaced). Review/edit/delete on the Memory page |
| 🔍 **Cross-chat recall** | Each turn: keywords → recent visible chats scanned → isolate-scored → top 3 turns (300-char centered snippets, 1 per chat) injected before your question when budget allows. Archived/hidden chats excluded |
| 🎯 **Ranked injection** | System prompt gets only query-relevant facts (600-char budget), not a dump |
| 🧠 **Proof chip** | Assistant bubble shows **Memory +N** when past turns informed the answer; System Logs rows `New memory stored` / `Recalled N past turn(s)` |
---
## ☁️ Cloud AI Providers
> **23+ providers, one unified interface.** Every provider implements the same `CloudProvider` interface and registers in `CloudProviderRegistry`.
<table>
<tr>
<td width="50%" valign="top">
### 🔀 Aggregators / Gateways
| Provider | Highlights |
| :--- | :--- |
| **OpenRouter** | Multi-provider gateway — hundreds of models, free tier |
| **Hugging Face** | Inference Providers router — dozens of upstream vendors |
| **xKiro** | Smart-routing gateway, free tier, all vendors |
| **TokenRouter** | Unified hub — 100+ vendor models |
| **AgentRouter** | Non-profit OpenAI gateway — Claude / GPT / Gemini / GLM |
| **OrcaRouter** | Cost-price gateway — `vendor/model` IDs, `orcarouter/auto` |
| **APInex** | One-key gateway — OpenAI / Anthropic / Gemini / DeepSeek / Kimi / Zhipu / xAI |
</td>
<td width="50%" valign="top">
### 🏢 First-Party Providers
| Provider | Models |
| :--- | :--- |
| **OpenAI** | GPT-5.2, GPT-4o, etc. |
| **Anthropic** | Claude Sonnet 4 |
| **Google Gemini** | Gemini 2.5 Flash |
| **DeepSeek** | deepseek-v4-flash |
| **Z.AI** | GLM-5.3 series + free GLM Flash models |
| **xAI Grok** | Grok-4, Grok-3, vision |
| **Perplexity** | Sonar — web-grounded answers |
</td>
</tr>
<tr>
<td width="50%" valign="top">
### ⚡ High-Speed Inference
| Provider | Models |
| :--- | :--- |
| **Groq** | Ultra-fast LPU — Llama, Qwen, DeepSeek |
| **Cerebras** | Fastest inference — Llama, Qwen, GPT-OSS |
| **Mistral AI** | Large, Codestral, Pixtral |
| **Together AI** | Llama, DeepSeek, Qwen turbo |
| **Fireworks AI** | Production open-model hosting |
| **NVIDIA NIM** | Llama 3.1, etc. |
| **Cohere** | Command-A, Command-R, Aya |
</td>
<td width="50%" valign="top">
### 🎨 Special & Utilities
| Feature | Details |
| :--- | :--- |
| **Stability AI** | SD3.5 Flash cloud image generation |
| **Cloud usage estimates** | Explore → Online header card: per-provider in/out tokens + calls (chars/4, no pricing table), resettable |
| **Custom endpoints** | OpenAI-compatible with multiple profile support |
</td>
</tr>
</table>
> [!IMPORTANT]
> **Unified plugin architecture** — All providers share `lib/services/cloud/providers/`. Model lists auto-fetch from each provider's API on key save/refresh (with catalog fallback for providers without a `/models` endpoint), with FREE model tagging and filtering where supported. With **Auto Tune** enabled, cloud requests carry no output-token cap — models with 128K+ output budgets answer at full length.
### 🏷️ Auto-Detected Company Filter
> For aggregator providers that host multiple companies' models under `vendor/model` IDs (OpenRouter, Hugging Face, xKiro, TokenRouter, NVIDIA NIM, Together AI, Fireworks…), a company filter chip row appears automatically above the model list.
| Behavior | Detail |
| :--- | :--- |
| 🎯 **Derived from model IDs** | Chips are computed from the fetched model list itself |
| 🆕 **Zero-config updates** | When a new vendor appears on the aggregator, its chip shows on the next refresh — no app update needed |
| ✨ **Prettified names** | Known vendor names/icons are styled; unknown ones fall back to capitalized IDs |
---
## 🧩 Skills — Offline Instruction Extensions
> Skills are **offline, static prompt-injection blocks** (markdown) that teach the model how to handle a class of tasks. **No network, no SDK** — just text appended to the system prompt. Works identically for **local** (llama.cpp / LiteRT-LM) and **cloud** models.
<details>
<summary><b>🔧 Architecture & Data Model — click to expand</b></summary>
<br/>
| Component | Path | Purpose |
| :--- | :--- | :--- |
| **Data model** | `lib/models/skill_model.dart` | `id / name / description / author / version / content / enabled / isBuiltIn / source / createdAt`; plain text; file fallback for >100 KB |
| **Registry** | `lib/services/skills/skill_registry_service.dart` | Hive `skillsBox` with `installBuiltIns()` (idempotent), `importFromMarkdown`, `enable / disable / delete / getEnabled / getAll`; 5 bundled starters in `assets/skills/` seeded on first run |
| **Injection** | `lib/services/skills/skill_injector.dart` | `buildInjectedContext()` / `buildForSkills()` concatenate skills as `### Skill: {name}` blocks, stably ordered |
**🧠 Intelligent per-prompt activation:**
- `selectRelevantSkills(prompt, max 2)` scores enabled skills by keywords, Bangla-script detection, code-block presence, etc. (threshold `0.6`)
- Only matching skills are injected via `SettingsController.effectiveSystemPromptForPrompt(model, prompt)` → read by `ChatController` for every generation
- The assistant bubble then shows **"Skills used"** chips (check + name, e.g., *Code Reviewer*) — exactly like ChatGPT/Claude's skill indicator
- **If none match: no injection, no chip** — keeps the system prompt lean
</details>
### 📦 Starter Skills *(real content, not placeholders)*
| Skill | Purpose | Trigger Heuristics |
| :--- | :--- | :--- |
| 🌐 **Bangla-English Translator** | Bilingual Banglish handling | Bangla script detection |
| 🔍 **Code Reviewer** | Flutter / Dart / Python / JS senior review | Code-block presence |
| ⚡ **On-Device Efficient Prompting** | Concise, structured for 2K–8K contexts | Local model detection |
| 📚 **Study Helper — ELI12** | Analogy + quiz format | "explain", "teach" keywords |
| ✍️ **Creative Writer** | Stories / poems / scripts | Creative keywords |
### 🎛️ Skills UI
<table>
<tr>
<td width="50%" valign="top">
**📍 Access Points**
- Dedicated **Explore → Skills** tab (4-way toggle: Local / Online / Skills / MCP)
- Same card in **Settings › Config → SKILLS** (next to Global System Prompt) for quick access
</td>
<td width="50%" valign="top">
**📥 Import Methods**
- **Import → From file** (file_picker)
- **Browse Anthropic skills** (`anthropics/skills` via GitHub REST + raw fetch, cached 6h, rate-limit safe)
- **From URL** — any raw markdown URL, size/type checked, preview-before-enable
</td>
</tr>
</table>
- Preview dialog shares a re-importable `.md` bundle
- GitHub browse is a flat list (no search/categories) with per-item **Import**
- URL import shows preview (frontmatter-parsed name/description) before save
- All imports converge on `importFromMarkdown`
---
## 🔌 Custom MCP Server — Single Remote Connection *(no marketplace)*
> A power-user setting in **Settings › Config** to connect one user-provided **remote** MCP server (Streamable HTTP / SSE). No stdio, no marketplace, no multi-server, no OAuth UI — **intentionally minimal**.
<table>
<tr>
<td width="50%" valign="top">
### 🔨 Implementation
**SDK**
- `dart_mcp ^0.5.2` (labs.dart.dev) + `mcp_client` fallback checked
- Only remote transport is exposed
- Hand-rolled JSON-RPC avoided where the SDK fits
- Flutter ergonomics fallback is HTTP/SSE via `dio`
**Connection** (`lib/services/mcp/mcp_connection.dart`)
- `connect()` — `initialize → notifications/initialized → tools/list`
- `listTools()`, `callTool(name, args)` (size-capped, untrusted), `disconnect()`
- `statusStream` (disconnected / connecting / connected / error) with typed errors (auth / timeout / unreachable)
- Session ID via `mcp-session-id` header, SSE data-frame parsing, bearer auth from secure storage
**Config** (`lib/services/mcp/mcp_config.dart`)
- Single `McpConfig` (name / url / transport / bearer / enabled)
- Transport auto-inferred from URL
- Hive `mcpBox` single record
**Registry** (`lib/services/mcp/mcp_registry_service.dart`)
- Hive + `flutter_secure_storage` (Keystore / Keychain) for token — **never in Hive / plaintext**
- `saveConfig / testConnection / enable / disable / remove`
- Status/tools observables
- `WidgetsBindingObserver` to disconnect on background and reconnect on resume
</td>
<td width="50%" valign="top">
### 🧠 LLM Wiring
- `CloudProvider.supportsMcpTools` + `buildRequestBody(mcpTools)` adds `tools` / `tool_choice: auto` for OpenAI-compatible providers
- `OpenAICompatibleProvider.sendMessage/streamMessage` detects `tool_calls`, calls `McpRegistryService.callTool`, round-trips `tool` result via second request, then returns final answer
- **Streaming** buffers tool deltas and re-emits final answer chunked
- **Local models skip tools** (no reliable structured output) but still benefit from Skills
- Offline / unreachable still advertises tools; failed `callTool` surfaces as error tool-result
### 🖥️ UI
- **Explore → MCP** tab + same form in **Settings › Config → CUSTOM MCP SERVER** (`_McpSection` + `explore_skills_mcp_tabs.dart`)
- Single form: name, URL, bearer token (eye toggle), transport auto
- **Save / Test / Enable-Disable** (with pre-enable tool preview dialog) **/ Remove**
- Live status dot + banner, exposed-tools list (name + description) before enabling
- 🔒 Stored token **never** enters LLM context
- Explore's 4-way toggle (Local / Online / Skills / MCP) keeps everything discoverable in one place
</td>
</tr>
</table>
> [!WARNING]
> **Ask-before-run** — every tool call shows **Deny / Allow once / Always-allow** (fail-closed, per-tool memory); toggle in the MCP header card.
---
## 🔌 Built-in OpenAI-Compatible API Server
> Turn your phone into an OpenAI-compatible endpoint on port **8080** — use local models from any client on your network.
| Feature | Details |
| :--- | :--- |
| 🌐 **Expose local models** | OpenAI-compatible API on port **8080** |
| 🔑 **Optional API key authentication** | Toggle on/off |
| 🚦 **Rate limit** | 120 POSTs/min/IP (429 response), in-memory request ring (see `/v1/server/capabilities`) |
| ⚠️ **Honest 400** | for `/v1/embeddings` (no on-device embedding mode) |
| 📋 **Recent-request viewer** | in Settings → Nodes (last 10, auto-refresh) |
| 🔌 **Compatibility** | Works with any OpenAI-compatible client on your network |
**Example usage:**
```bash
curl http://<device-ip>:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "local",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
---
## 🧩 Additional Features
### 🧭 Navigation
> **Chat · Explore · Toolkit · Settings**
| Destination | Contents |
| :--- | :--- |
| 🔍 **Explore** | **Model Hub** (Local / Online / Skills / MCP scopes) |
| 🧰 **Toolkit** | Battle Arena + Slide Maker + CubicWeb Builder widget cards |
| ⚙️ **App Settings** | Six tabs — **General** (theme, orbs, language, startup), **Nodes** (local API server), **Config** (diagnostics, hardware, inference mode, system prompt, Skills, Custom MCP Server), **Parameters** (local model & imaging parameters), **Dev Tools** (Strict RAM guard, Developer tools, Linux runtime), **Data** (backups, export/import, usage stats, System logs) |
### 💬 Chat & Sessions
| Feature | Description |
| :--- | :--- |
| 📚 **Multi-session chat** | History (Hive persistence) + **full-text searchable** sidebar drawer (`HiveService.searchMessages` scans `content`) with swipe-to-delete, long-press Export/Delete, and header Export (`share_plus` Markdown) |
| 💬 **Message actions** | Copy, **share**, regenerate, branch into a new chat, and edit with full revision history (step back and forth between edited versions) |
| 📝 **Prompt templates** | 6 built-ins + custom (composer button → bottom sheet, one-tap insert, Hive-persisted) |
| ☑️ **Multi-select** | Long-press or header toggle → bulk copy/share/delete via the selection bar |
| 📌 **Per-chat model pin** | Switcher-sheet toggle pins the active local/cloud model to one chat (📌 pill), auto-applied on open |
| ⚖️ **Side-by-side compare** | One-shot challenger answers the same prompt (`⚖️` message), primary setup restored afterwards |
| 🏟️ **Battle Arena** | Chat ⋮ menu → up to **4 cloud models** race one prompt with live monitor + overall verdict |
| 🏷️ **Chat labels** | Free-form folder label per chat with drawer filter chips |
| 🔒 **Per-chat lock** | Device-auth gate on open; **undo delete** (5s snackbar) |
| 📄 **Whole-chat PDF** | Chat menu export alongside Markdown / .txt |
| 💻 **Code blocks** | Syntax highlighting, one-tap copy, and export/share |
### 🎨 Visual & UX
| Feature | Description |
| :--- | :--- |
| 🔮 **Thinking Orbs** | 3D particle sphere animation (9 states: Working, Searching, Solving, Listening, Connecting, Weaving, Composing, Breathing, Shaping) with grayscale ink, size-aware speeds, and phase-continuous hard cuts |
| 🖼️ **Empty state** | `assets/icons/CubicLM.png` 64×64 + animated shimmer above suggestions — never a blank screen |
| 🔄 **Header & composer sync** | `chat_view.dart:302,1185` both `Obx` on `InferenceService.loadedModelName` / `LocalImageService.loadedModelName` + `SettingsController` mode |
| 🏷️ **Chat enrichments** | Assistant bubbles show **Sources** chips (favicon + domain + title, tap to open) when web search was used, and **Skills used** chips (check + skill name) when a prompt matched enabled skills |
### 🔔 Notifications & Background
<details>
<summary><b>Click to expand</b></summary>
<br/>
**🔔 Notification History**
- Bell in chat header with unread badge
- Slide-in page grouped by **Today / Yesterday / weekday** with relative timestamps (Just now / 5m ago / 2h ago)
- Swipe-to-delete, mark-all-read & clear-all
- Every model switch (local / cloud / back-to-local) auto-logs with timestamp and shows as a **top spring-animated toast** (`AppSnackbar.showTop` `lib/utils/app_snackbar.dart:29`)
- Hive-persisted, max 100
- `LogView` copy now also uses top toast, not bottom
**📥 Background Model Download**
- Foreground service — downloads keep running when the app is closed or swiped away
- Notification with **Pause / Cancel** actions
- HTTP Range resume picks up at the **exact byte offset** after pause or app restart (`START_STICKY`)
- **🆕 Resume race + atomicity fixed** — `download_service:68` atomic `.tmp→rename` for `paused_downloads.json`; `download_native:427` `validateDownloadedFile()` (GGUF `GGUF` / litertlm `LITERTLM` / safetensors `{` + 1% size); `reconcileActiveDownloads` prefers native and cleans stale completed before restore; `model_controller:199` async header check for imported files
**🔔 Background-done Ping**
- Answers finishing while backgrounded fire a notification with preview
</details>
### 📎 Input & Sharing
- **Share-target (Android)** — text shared from any app lands in the composer via `ACTION_SEND` + method channel (cold + warm paths)
- **Offline outbox** — failed sends queue and auto-send when back online
- **Attachments** — camera, gallery, or files (PDF/text extraction)
- **Image sharing and export**
- **Dark/light theme** with adjustable font scale
### 🔧 System
- 🔥 **Firebase Crashlytics** integration
- 🔋 **Background service** and boot persistence
- 📥 **In-app model download** with byte-exact pause / resume / cancel, plus file import
---
## 🌐 CubicWeb Builder *(Toolkit)* — `v1.12.0`
> **The AI-powered web builder baked into CubicLM.** Stream code, preview live, deploy in one click.
<table>
<tr>
<td width="50%" valign="top">
### 🎬 Build Experience
- **Live streaming builds** — files appear in the explorer as the AI writes (writing badges, live highlighted editor)
- Static preview reloads live; cancel rolls back to checkpoint
- **Plan mode, checkpoints/undo, diff view**
- **Responsive viewports** (mobile / tablet / desktop)
- Screenshot-to-code, keyboard shortcuts, 6 project templates
### 🖥️ Runtime
- **Real local runtime** — project detection (static / Vite / Next / Node)
- Source validation
- Dev-server manager (install, free-port pick, URL parse, health check, crash watcher, restart)
- Real shell terminal
### 🚀 Deploy & Share
- One-click **Vercel / Netlify** deploy
- Share links, GitHub export
- Component library
- Extended-thinking + web-search toggles
- Browser auto-test
</td>
<td width="50%" valign="top">
### ⚛️ Next.js Pipeline
- Atomic writes, byte-for-byte integrity gates
- Framework adapters
- `npm run build` validation
- External-browser preview
### 🧑💻 Developer Tools
- **Terminal + CLI manager** — real shell with history/autocomplete/stdin attach
- One-tap installs for **Claude Code, OpenCode, Cline, Kilo**
- Open / Verify / Update / Repair / Uninstall with persistent registry
### 📊 Diagnostics & Cloud Tools
- **CubicWeb System Logs** — structured `CW-*` diagnostics separate code bugs from missing runtimes / device limits (see Settings › Config › System Logs + AppBar activity icon); AI skips rewrites for environment failures
- **Cloud model tools** — import from `/models` with new-count report, test-all with online/failed dots, auto-hide failed, auto-sync interval (configurable)
</td>
</tr>
</table>
---
## 🖥️ Universal Multi-Platform — *One Codebase, Three Shells*
> [!IMPORTANT]
> **Web ⇄ Windows Desktop ⇄ Android** — same `lib/` product, **not three forks**. Per `docs/PLATFORM_DIFFERENCES.md` (AUDIT→PLAN→BUILD).
<table>
<tr>
<td width="33%" valign="top">
### 🤖 Android *(primary, full)*
- `android/` Gradle 8.14
- `ModelDownloadService.kt` (FGS, Range, `START_STICKY`)
- Native storage
- Background service & boot persistence
- **Full local inference** via llama.cpp + LiteRT-LM
</td>
<td width="33%" valign="top">
### 🌐 Web *(Flutter Web)*
- `web/` static shell (`index.html`, `manifest.json`)
- Hive IndexedDB
- `dart:io` stubs (`download_web.dart`, `inference_stub.dart`)
- `flutter build web` → `build/web`
- **Cloud-only** until `dart:ffi` is solved
</td>
<td width="33%" valign="top">
### 🪟 Windows Desktop
- **Flutter Windows**, not Tauri per §8.5
- `windows/` CMake runner
- `window_manager 0.4.3` (`400×700` min, `1280×800` default, centered, `CubicLM` title, `waitUntilReadyToShow`)
- Native file dialogs via `file_picker`
- `flutter build windows` → `build/windows/runner/Release/cubiclm.exe`
- **Cloud-only** until `llama.dll` is ported
</td>
</tr>
</table>
<details>
<summary><b>🤔 Why Flutter Windows, not Tauri?</b></summary>
<br/>
Existing `shared` is Dart (`lib/`), not TS — Tauri would require rewriting `lib/` in TS/Svelte or bridging Dart→Rust; `flutter create --platforms=windows` reuses **100% of `lib/` for free** (lower total cost, §8.5 justification).
</details>
### 🧭 Architecture & Consistency
| Principle | Details |
| :--- | :--- |
| **Single source of truth** | `shared/constants/platform_links.dart` + `lib/shared/constants/platform_links.dart` (now set to `https://cubiclm.vercel.app` + GitHub Releases). `About → AVAILABLE ON` links to the *other two* platforms + centralized `CHANGELOG.md`, never to itself, via `launchUrl(externalApplication)` (Web `_blank`, Desktop OS browser, Android Browser tab) — see `docs/PLATFORM_LINKS.md` |
| **Responsive, not forked** | `lib/shared/theme/tokens.dart` (`Breakpoints.phone 360 / tablet 600 / laptop 900 / desktop 1280 / wide 1920`, `Spacing`, `TypographyTokens`) + `Dt` tokens; `HomeView._isWide 800` (sidebar vs bottom nav), `Flexible` pill `14` chars, `Expanded` header — verified `360/768/1280/1920` + manual resize `400×700` → `1920` per §5.3 |
| **Docs** | `docs/PLATFORM_DIFFERENCES.md` (local inference cloud-only on Web/Windows until `local_plugins/llama_flutter_windows` ported), `docs/ARCHITECTURE.md`, `docs/BUILD_AND_RUN.md`, `scripts/build-all.ps1` / `.sh` |
| **Windows local inference** | *(intentional gap §8.3)* — `local_plugins` are Android FFI only → `supportsLocalInference=false` on `TargetPlatform.windows`, shows cloud banner; roadmap is `local_plugins/llama_flutter_windows` (`llama.dll`) |
### 🔄 In-Chat Model Switcher
> Opened from the chat header — mirrors the Explore page's layout.
<table>
<tr>
<td width="50%" valign="top">
**🏠 Local tab**
- Search box over downloaded models
- LiteRT / GGUF / "In memory" badges
- Live load progress
</td>
<td width="50%" valign="top">
**☁️ Cloud tab**
- Every configured provider gets a collapsible section styled like the Explore provider cards
- Count badges, FREE badge + filter chip
- Per-provider search
- Auto-detected company filter chips
- Scrollable boxed model list
- A global search box above matches models across **all providers at once** (results show the owning provider); picking a result switches the active provider automatically
</td>
</tr>
</table>
> [!TIP]
> Deactivating the active cloud provider switches inference back to local mode and **auto-loads the last downloaded model**.
---
## 🩺 System Diagnostics *(Settings › Config › System Logs)*
<table>
<tr>
<td width="50%" valign="top">
### 💚 Health Dashboard
Auto-detects **10 crash patterns**:
| # | Pattern |
| :---: | :--- |
| 1 | Model file missing |
| 2 | Context overflow |
| 3 | Model load failure |
| 4 | GPU error |
| 5 | Cloud API error |
| 6 | Out of memory |
| 7 | Generation hang |
| 8 | Stale multi-model slot |
| 9 | Import failure |
| 10 | Firebase init |
> `RenderFlex overflow` is logged as `ERROR [System]` but correctly shows **No crash patterns** (layout, not model).
### 🔎 Filters
- **Category filters** — System, Model, Cloud, Chat, Server, Image
- **Level filters** — ALL, ERROR, WARNING, INFO, DEBUG
- **Full-text search** across log messages and details
</td>
<td width="50%" valign="top">
### 💾 Persistence & Export
- **Log persistence** — logs survive app restarts (saved to JSON, max 500 entries)
- **Export** — copies full diagnostic report (health summary + all logs) to clipboard (top toast)
### 🔬 Deep Insights
- **Crash pattern details** — occurrence count, last-seen timestamp, and fix suggestion for each detected issue
- **Chat context proof** — every chat send logs `Chat context: N turns, ~M tokens…` (Chat category) so a "model forgot" report is instantly diagnosable
</td>
</tr>
</table>
---
## 🎨 Theming & UX Deep Dive
<details>
<summary><b>Click to explore the design system</b></summary>
<br/>
### 🎨 Color Palette
| Token | Value | Usage |
| :--- | :--- | :--- |
| `Dt.canvas` | `#F8F4ED` | Warm off-white canvas (matches native splash) |
| `Dt.accent` | `#FF4D00` | Primary orange accent (brand color) |
| `Dt.pill` | — | Pill-shaped buttons |
| `Dt.hairline` | — | Subtle 1px separators |
> Claude APK-measured warm palette, defined in `lib/core/design_tokens.dart`.
### 📐 Breakpoints
| Name | Width | Layout |
| :--- | :--- | :--- |
| `phone` | 360px | Bottom nav |
| `tablet` | 600px | Bottom nav |
| `laptop` | 900px | Sidebar nav |
| `desktop` | 1280px | Sidebar nav |
| `wide` | 1920px | Sidebar nav + wider gutters |
### 🔮 Thinking Orbs
3D particle sphere animation with **9 named states**:
`Working` · `Searching` · `Solving` · `Listening` · `Connecting` · `Weaving` · `Composing` · `Breathing` · `Shaping`
- **Grayscale ink** rendering
- **Size-aware speeds** — larger orbs rotate slower
- **Phase-continuous hard cuts** — no visual snapping
- **Random** shuffle or fixed state per context (chatting / image gen / analyzing)
- Live previews in the picker (**App Settings › Thinking Orbs**)
### ✨ Animation Timings
| Animation | Duration |
| :--- | :--- |
| Splash shimmer dwell | `1380ms` |
| Splash fade-out | `760ms` |
| Toast spring (top) | OS-default |
| Streaming flush (short) | `150ms` |
| Streaming flush (long) | `300ms` |
| Onboarding page transition | OS-default |
| Undo-delete snackbar | `5000ms` |
</details>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- SUPPORTED MODELS -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/ai/ai.gif" width="120" />
# Supported Models
<sub><i>18+ curated models across 3 runtimes — all downloadable in-app</i></sub>
</div>
### ⚡ LiteRT-LM *(on-device)*
| Model | Size | Params | Best For |
| :--- | ---: | :---: | :--- |
| **Qwen3-0.6B** | 586 MB | 0.6B | Smallest chat model for low-RAM phones |
| **Qwen2.5-1.5B Instruct** | 1.49 GB | 1.5B | Balanced int8 quantized chat model |
| **DeepSeek-R1-Distill-Qwen-1.5B** | 1.71 GB | 1.5B | Reasoning-focused model |
| **Gemma 4 E2B Instruct** | 2.46 GB | 2B | Google Gemma vision + chat |
| **Gemma 4 E4B Instruct** | 3.40 GB | 4B | Highest quality LiteRT option |
### 🐫 GGUF *(llama.cpp)*
| Model | Size | Params | Best For |
| :--- | ---: | :---: | :--- |
| **Kimi Moonlight 16B-A3B (Q3_K_S)** | 7.1 GB | 16B MoE (3B active) | High-capability MoE, efficient inference |
| **Qwen2.5-3B Instruct (Q4_K_M)** | 2.1 GB | 3B | Best mobile speed/quality |
| **Qwen2-VL-2B (Q4_K_M)** | 1.5 GB | 2B | Vision-capable |
| **Phi-3.5 Mini (Q4_K_M)** | 2.2 GB | 3.8B | Microsoft reasoning model |
| **Gemma 2 2B (Q4_K_M)** | 1.71 GB | 2B | Google lightweight chat |
| **Llama-3.2-3B Uncensored** | 2.1 GB | 3B | Unrestricted assistant |
| **Llama-3.2-1B Instruct** | 0.8 GB | 1B | Ultra-lightweight |
| **+ uncensored / abliterated variants** | — | — | Dolphin, SmolLM2, Gemma abliterated |
### 🎨 Image Generation *(Stable Diffusion 1.5)*
| Model | Size | Style |
| :--- | ---: | :--- |
| **DreamShaper 8 LCM** | 2.0 GB | Fast 4-step generation |
| **CyberRealistic V8 FP16** | 2.0 GB | Photorealistic, uncensored |
| **Realistic Vision V5.1 FP16** | 2.0 GB | Popular portrait / scene model |
| **AbsoluteReality 1.8.1** | 2.0 GB | General-purpose photorealistic |
| **AnyLoRA** | 2.0 GB | Anime / stylized |
### 📊 Model Selection Guide
| Device RAM | Recommended Models |
| :--- | :--- |
| **4 GB** | Qwen3-0.6B, Llama-3.2-1B, Qwen2.5-1.5B |
| **6 GB** | Gemma 2 2B, Qwen2-VL-2B, Phi-3.5 Mini |
| **8 GB** | Qwen2.5-3B, Llama-3.2-3B, Gemma 4 E2B |
| **12 GB+** | Gemma 4 E4B, Kimi Moonlight 16B-A3B |
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- TECH STACK -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
<div align="center">
<h1>🛠️ Tech Stack</h1>
<sub><i>Technologies powering CubicLM</i></sub>
</div>
<br/>
| Category | Technologies |
| :--- | :--- |
| 🎯 **Framework** | Flutter 3.x |
| 💻 **Language** | Dart, Kotlin, C++ (native plugins) |
| 🔄 **State Management** | GetX |
| 💾 **Local Storage** | Hive |
| 🌐 **Networking** | dio, http |
| 🧠 **Local Inference** | `llama_flutter_android`, `flutter_litert_lm`, `sd_flutter_android` (custom plugins) |
| ☁️ **Cloud Backend** | Firebase Core, Firebase Messaging, Firebase Crashlytics |
| 🌍 **Localization** | 15 languages — EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR<br>GetX Translations with Hive persistence<br>90+ keys — `nav_*`, `chat_*`, `model_*`, `nodes_*`, `about_*`, `settings_*`, `onboarding_*`<br>`fallbackLocale EN`<br>App Settings + bottom nav + all 4 views reactive via `'.tr'` |
| 📦 **Other Libraries** | `google_fonts` · `flutter_markdown` · `image_picker` · `share_plus` · `permission_handler` · `speech_to_text` · `lucide_icons` · `url_launcher` · `file_picker` · `flutter_secure_storage` · `dart_mcp` · `window_manager` |
<br/>
---
### 📊 Dependency Highlights
| Dependency | Purpose |
| :--- | :--- |
| `llama_flutter_android` | Custom plugin — llama.cpp FFI bindings for Android |
| `flutter_litert_lm` | Custom plugin — Google LiteRT-LM runtime bindings |
| `sd_flutter_android` | Custom plugin — Stable Diffusion inference |
| `dart_mcp ^0.5.2` | MCP client (labs.dart.dev) |
| `window_manager 0.4.3` | Windows desktop window sizing & positioning |
| `flutter_secure_storage` | Keystore / Keychain for MCP bearer tokens |
</div>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- PROJECT STRUCTURE -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 📂 Project Structure
</div>
<details>
<summary><b>🗂️ Click to expand full directory tree</b></summary>
<br/>
```text
lib/
├── main.dart # App entry point — critical path (Hive 5s + Settings), heavy services 2200ms deferred
├── core/
│ ├── app_translations.dart # GetX Translations — ~160 keys × 15 languages
│ ├── assets_data.dart # Embedded asset catalog helpers
│ ├── colors.dart # App color palette (warm Claude-inspired)
│ ├── constants.dart # Settings keys, model catalog, API endpoints
│ ├── languages.dart # 15 supported languages (code, name, nativeName, flag, Locale)
│ ├── routes.dart # Route definitions
│ └── theme.dart # Light/dark theme with warm accent palette
├── theme/
│ └── design_tokens.dart # Claude APK-measured warm palette (canvas #F8F4ED, pill, accent, hairline)
├── models/
│ ├── ai_model.dart # AI model data class
│ ├── chat_message.dart # Chat message (revision history + webSources + usedSkills)
│ ├── chat_session.dart # Chat session model
│ ├── cloud_provider_info.dart # Cloud provider metadata (split from cloud_model_controller)
│ ├── folder_model.dart # Chat folder/label model
│ ├── notification_entry.dart # Model-switch history entry
│ ├── preview_step.dart # Preview-pipeline step value type (split from agent_controller)
│ ├── project_model.dart # CubicWeb project model
│ ├── skill_model.dart # Skill (name/description/content/enabled/isBuiltIn/source)
│ ├── task_model.dart # Automated task model
│ └── web_source.dart # Web source (url/domain/favicon/title/success)
├── controllers/ # Big controllers are split: main + `part` files (one per feature)
│ ├── agent_controller.dart # Agent-IDE orchestrator (main: fields, lifecycle)
│ │ ├── agent_controller_workspace.dart # console, assets, symbols, attachments, mentions
│ │ ├── agent_controller_chat.dart # transcript, build steps, terminal buffer
│ │ ├── agent_controller_streaming.dart # streaming merge, fidelity checks, file ops
│ │ ├── agent_controller_generation.dart # project generation, plan, repair
│ │ └── agent_controller_runtime.dart # preview serve, dev server, terminal, CLI
│ ├── battle_arena_controller.dart # Side-by-side model comparison
│ ├── chat_controller.dart # Chat logic (main) + 7 part files
│ │ ├── chat_controller_sessions.dart # sessions, folders, model pins
│ │ ├── chat_controller_messages.dart # selection, revisions, compare, export
│ │ ├── chat_controller_generation.dart # send pipeline, context budget, web, skills
│ │ ├── chat_controller_attachments.dart # image/photo/file picking, text extraction
│ │ ├── chat_controller_voice.dart # TTS playback, voice mode, speech-to-text
│ │ ├── chat_controller_templates.dart # prompt templates (built-ins + custom)
│ │ └── chat_controller_find.dart # find-in-page + history search
│ ├── cloud_model_controller.dart # Cloud selection (main) + 4 part files
│ │ ├── cloud_providers.dart # registry, ordering, filters, pins, key verify
│ │ ├── cloud_models.dart # per-provider models, custom profiles
│ │ ├── cloud_health.dart # health probes, test-all, persistence
│ │ └── cloud_sync_parse.dart # auto-sync + model-list sync/parse
│ ├── home_controller.dart # Tab navigation, model resume (520ms delay, async file check, 90s crash guard)
│ ├── model_controller.dart # Local models (main) + 4 part files
│ │ ├── model_catalog.dart # OTA/bundled catalog + custom URL models
│ │ ├── model_downloads.dart # downloads, pause/resume/cancel, delete
│ │ ├── model_loading.dart # load + file validation (SafeTensors/LiteRT)
│ │ └── model_safety.dart # RAM-guard confirmations + dialogs
│ ├── server_controller.dart # Local API server
│ ├── settings_controller.dart # Settings (main) + 5 part files
│ │ ├── settings_loading.dart # startup load, migration, persistence
│ │ ├── settings_cloud.dart # providers, API keys, sync, shared generation
│ │ ├── settings_browser.dart # parameters, browser opts, bookmarks, defaults
│ │ ├── settings_media.dart # SD/WebGPU, cameras, TTS/STT, vision, audio
│ │ └── settings_appearance.dart # fonts, themes, lock, export, reset, dev tools
│ ├── slide_deck_controller.dart # Slide Maker engine
│ ├── task_controller.dart # Automated task execution
│ └── vision_live_controller.dart # Live vision camera
├── services/
│ ├── agent_workspace.dart # Skill/agent workspace persistence
│ ├── app_log_service.dart # App logging with categories & crash detection
│ ├── chat_backup.dart # Chat backup/restore
│ ├── cloud_service.dart # Multi-provider cloud API (delegates to providers) + usage tracking
│ ├── code_interpreter_service.dart # Sandboxed code execution
│ ├── crash_reporting_service.dart # Firebase Crashlytics
│ ├── deploy_service.dart # Vercel/Netlify deploy
│ ├── device_info_native.dart # Native device info (Android)
│ ├── device_info_service.dart # RAM/tier + SoC/GPU detection
│ ├── device_info_web.dart # Web device info stubs
│ ├── document_extractor_service.dart # PDF/text extraction
│ ├── download_native.dart # Resumable streaming downloader (HTTP Range)
│ ├── download_service.dart # Download orchestrator (native FGS + Dart fallback)
│ ├── download_web.dart # Web stubs
│ ├── execution_service.dart # Task execution engine
│ ├── hive_service.dart # Local persistence (7 boxes, per-box 3s timeout)
│ ├── image_generation_notification_service.dart
│ ├── inference_android.dart # Android llama.cpp / LiteRT engine bridge
│ ├── inference_gguf.dart # GGUF inference backend
│ ├── inference_litert.dart # LiteRT-LM inference backend
│ ├── inference_service.dart # Cross-platform inference orchestrator
│ ├── inference_stub.dart # Web/no-ffi stub
│ ├── inference_text.dart # Text inference helpers
│ ├── inference_types.dart # Inference type definitions
│ ├── local_image_service.dart # Stable Diffusion inference
│ ├── memory_service.dart # Context memory management
│ ├── notification_history_service.dart # Model-switch history (Hive, max 100)
│ ├── openai_server_service.dart # Built-in OpenAI-compatible server
│ ├── openai_server_service_io.dart # IO platform implementation
│ ├── openai_server_service_stub.dart # Web stub
│ ├── preview_server.dart # CubicWeb preview server
│ ├── sd_isolate_processor.dart # SD processing in isolates
│ ├── sd_isolate_worker.dart # SD isolate worker
│ ├── sd_isolate_worker_io.dart # IO platform SD worker
│ ├── sd_isolate_worker_web.dart # Web platform SD worker
│ ├── secure_key_store.dart # Secure key storage
│ ├── soc_family.dart # SoC family detection
│ ├── stats_service.dart # Usage statistics
│ ├── tts_service.dart # Text-to-speech
│ ├── update_service.dart # App update checker
│ ├── usage_tracker_service.dart # Per-provider/model token usage (Hive JSON, chars/4)
│ ├── vector_service.dart # Vector embedding service
│ ├── web_fetch_service.dart # URL fetching → clean text + WebSource
│ ├── win_toast_io.dart # Windows toast notification (IO)
│ ├── win_toast_notify.dart # Windows toast notification
│ ├── win_toast_stub.dart # Windows toast stub
│ ├── browser/
│ │ └── adblock_service.dart # Privacy browser adblock (318 rules)
│ ├── cloud/ # Cloud provider plugin architecture
│ │ ├── cloud_provider.dart # Abstract CloudProvider interface
│ │ ├── cloud_provider_config.dart # Provider configuration
│ │ ├── cloud_provider_registry.dart # Provider registry (ID → instance)
│ │ ├── model_health.dart # Model health tracking
│ │ └── providers/ # 26 provider files
│ │ ├── openai_compatible_provider.dart
│ │ ├── openai_provider.dart
│ │ ├── anthropic_provider.dart
│ │ ├── google_provider.dart
│ │ ├── deepseek_provider.dart
│ │ ├── zai_provider.dart
│ │ ├── groq_provider.dart
│ │ ├── mistral_provider.dart
│ │ ├── together_provider.dart
│ │ ├── xai_provider.dart
│ │ ├── perplexity_provider.dart
│ │ ├── cerebras_provider.dart
│ │ ├── fireworks_provider.dart
│ │ ├── cohere_provider.dart
│ │ ├── huggingface_provider.dart
│ │ ├── xkiro_provider.dart
│ │ ├── tokenrouter_provider.dart
│ │ ├── agentrouter_provider.dart
│ │ ├── orcarouter_provider.dart
│ │ ├── apinex_provider.dart
│ │ ├── kimi_provider.dart
│ │ ├── nvidia_provider.dart
│ │ ├── openrouter_provider.dart
│ │ ├── stability_provider.dart
│ │ └── custom_provider.dart
│ ├── cubicdata/ # CubicDataSheet engine
│ │ ├── controller.dart
│ │ ├── formulas.dart
│ │ ├── models.dart
│ │ ├── search.dart
│ │ └── vault_store.dart
│ ├── cubicweb/ # CubicWeb event system
│ │ ├── cubicweb_event.dart
│ │ └── cubicweb_logger.dart
│ ├── mcp/ # MCP (Model Context Protocol)
│ │ ├── mcp_config.dart
│ │ ├── mcp_connection.dart
│ │ └── mcp_registry_service.dart
│ ├── runtime/ # CubicWeb dev-server + CLI manager
│ │ ├── ansi.dart
│ │ ├── cli_manager.dart
│ │ ├── cli_manifest.dart
│ │ ├── cli_providers.dart
│ │ ├── cloud_runtime.dart
│ │ ├── dev_server_manager.dart
│ │ ├── dev_url_parser.dart
│ │ ├── framework_runtime.dart
│ │ ├── preview_router.dart
│ │ ├── process_runner.dart
│ │ ├── project_detector.dart
│ │ ├── project_validator.dart
│ │ ├── runtime_manager.dart
│ │ └── frameworks/ # Framework adapters
│ │ ├── framework.dart
│ │ ├── nextjs.dart
│ │ ├── node_generic.dart
│ │ ├── static_site.dart
│ │ └── vite.dart
│ └── skills/ # Skills system
│ ├── skill_registry_service.dart
│ ├── skill_injector.dart
│ ├── github_skill_source.dart
│ └── url_skill_source.dart
├── views/
│ ├── splash_view.dart # 1380ms shimmer + 760ms fade-out
│ ├── onboarding_view.dart # 3-page PageView + dots + Hive persist
│ ├── home_view.dart # Main navigation scaffold (IndexedStack 4 tabs)
│ ├── chat_view.dart # Chat interface
│ ├── model_view.dart # Model Hub — 4-way toggle (Local/Online/Skills/MCP)
│ ├── explore_skills_mcp_tabs.dart # Explore Skills + MCP tabs
│ ├── server_view.dart # Node manager (Settings → Nodes tab)
│ ├── settings_view.dart # Config sections
│ ├── app_settings_view.dart # App Settings
│ ├── language_picker_view.dart # Full-page language picker
│ ├── about_view.dart # About page
│ ├── notification_history_view.dart # Notification history page
│ ├── log_view.dart # System diagnostics viewer (Live Logs + Saved Files)
│ ├── system_logs_view.dart # CubicWeb system logs
│ ├── task_view.dart # Automated tasks
│ ├── toolkit_view.dart # Toolkit hub (Battle Arena, Slide Maker, CubicWeb Builder)
│ ├── battle_arena_view.dart # Side-by-side model comparison
│ ├── agent_ide_view.dart # Agent IDE (main) + 7 part files + markdown builders
│ │ ├── agent_ide_mentions.dart # @-mention overlay + picker
│ │ ├── agent_ide_sheets.dart # system prompt, assets, brand, voice sheets
│ │ ├── agent_ide_command.dart # command palette, ask-bar, bottom meter
│ │ ├── agent_ide_panes.dart # preview, dev-tools, terminal, status panes
│ │ ├── agent_ide_chat.dart # chat pane, actions, templates
│ │ ├── agent_ide_dialogs.dart # asset-gen + global-search dialogs, file tabs
│ │ ├── agent_ide_files.dart # files pane, tree, console, editor
│ │ └── agent_ide_markdown.dart # architecture/component markdown builders
│ ├── gallery_view.dart # Image gallery
│ ├── slide_deck_view.dart # Slide Maker composer (main) + 3 part files
│ │ ├── slide_deck_sheets.dart # style/plus/theme/translate/data/URL sheets
│ │ ├── slide_deck_browser.dart # sorter, deck bar, carousel, slide cards
│ │ └── slide_deck_canvas.dart # slide canvases + image controls
│ ├── update_view.dart # Update checker
│ ├── update_settings_view.dart # Update settings
│ ├── chat/ # Chat decomposition
│ │ ├── chat_bars.dart
│ │ ├── chat_dialogs.dart
│ │ ├── chat_format.dart
│ │ ├── chat_sidebar.dart
│ │ ├── chat_widgets.dart
│ │ ├── empty_state.dart
│ │ ├── input_bar.dart
│ │ ├── project_context_view.dart
│ │ ├── selection_bar.dart
│ │ └── template_sheets.dart
│ ├── cubicdata/ # CubicDataSheet views
│ │ ├── dashboard_view.dart
│ │ ├── datasheet_home_view.dart
│ │ ├── doc_view.dart
│ │ ├── hybrid_view.dart
│ │ ├── palette_view.dart
│ │ └── sheet_view.dart
│ ├── cubicweb/ # CubicWeb Builder views
│ │ ├── agent_preview.dart
│ │ ├── browser_view.dart
│ │ ├── browser_sheets.dart # bottom sheets + dialogs (split from browser_view)
│ │ ├── browser_home.dart # home-tab content (split from browser_view)
│ │ ├── chat_cards.dart
│ │ ├── component_card.dart
│ │ ├── diff_view.dart
│ │ ├── file_cards.dart
│ │ ├── knowledge_graph_view.dart
│ │ ├── project_sheets.dart
│ │ ├── responsive_grid_view.dart
│ │ └── version_timeline.dart
│ ├── explore/ # Explore tab components
│ │ ├── add_model_sheet.dart
│ │ ├── local_model_card.dart
│ │ ├── provider_cards.dart
│ │ ├── provider_dialogs.dart
│ │ ├── provider_theme.dart
│ │ └── toolkit_tab.dart
│ ├── settings/ # Settings sub-sections
│ │ ├── apple_widgets.dart
│ │ ├── device_card.dart
│ │ ├── model_params.dart
│ │ └── skills_section.dart
│ └── slides/ # Slide Maker sub-views
│ ├── slide_canvas.dart
│ ├── slide_charts.dart
│ ├── slide_dialogs.dart
│ ├── slide_outline_view.dart
│ ├── slide_painters.dart
│ └── slide_present_view.dart
├── widgets/
│ ├── app_ui.dart # Shared UI components
│ ├── artifact_renderer.dart # Markdown/artifact rendering
│ ├── attachment_preview.dart # Attachment preview chips
│ ├── chat_branch_timeline.dart # Branch history timeline
│ ├── chat_bubble.dart # Message bubble (main) + 3 part files
│ │ ├── chat_bubble_actions.dart # action bar, branch picker, TTS controls
│ │ ├── chat_bubble_bars.dart # context menu, artifact/recall/skills/source bars
│ │ └── chat_bubble_helpers.dart # badges, time/cost formatting, text cleanup
│ ├── citation_chip.dart # Source citation chip (favicon + domain)
│ ├── citation_link_builder.dart # Citation-link markdown builder (split from chat_bubble)
│ ├── cli_sheets.dart # CLI terminal sheets
│ ├── code_block.dart # Syntax-highlighted code blocks
│ ├── image_viewer.dart # Full-screen image viewer
│ ├── model_switcher_sheet.dart # In-chat model switcher (main) + 3 part files
│ │ ├── model_switcher_widgets.dart # rows, headers, scope toggle
│ │ ├── model_switcher_local.dart # local-model tab
│ │ └── model_switcher_cloud.dart # cloud-model tab
│ ├── thinking_orb.dart # 3D particle sphere animation (9 states)
│ ├── thought_disclosure.dart # Reasoning tag expansion
│ ├── typing_indicator.dart # Typing animation
│ ├── typing_text.dart # Typewriter text animation
│ └── voice_overlay.dart # Voice input overlay
├── ffi/
│ ├── sd_ffi_bindings.dart # FFI bindings for SD native lib
│ ├── sd_ffi_bindings_io.dart # IO platform bindings
│ └── sd_ffi_bindings_web.dart # Web platform bindings
├── utils/
│ ├── app_snackbar.dart # Top spring-animated toast
│ ├── artifact_parser.dart # Markdown artifact extraction
│ ├── battle_scoring.dart # Battle Arena scoring
│ ├── export_file.dart # Log export (copy/share/save)
│ ├── history_budget.dart # Token budget trimming
│ ├── prompt_export.dart # Chat export (Markdown/PDF/TXT)
│ ├── slide_deck.dart # Slide deck data model + PPTX import
│ ├── slide_palette.dart # Slide color palette derivation
│ ├── slide_pptx.dart # PPTX generation
│ ├── syntax_highlight.dart # Code syntax highlighting
│ ├── thought_parser.dart # <thought> tag parser
│ ├── web_download.dart # Cross-platform web download
│ ├── web_download_stub.dart # Web stub
│ ├── web_download_web.dart # Web platform download
│ ├── web_notify.dart # Web notification
│ ├── web_notify_stub.dart # Web stub
│ ├── web_notify_web.dart # Web platform notification
│ └── web_project.dart # Web project helpers
└── shared/
├── constants/
│ └── platform_links.dart # Centralized platform URLs
└── theme/
└── tokens.dart # Breakpoints, Spacing, TypographyTokens
local_plugins/
├── llama_flutter_android/ # llama.cpp Flutter plugin (GGUF inference)
├── flutter_litert_lm/ # Google LiteRT-LM Flutter plugin
├── sd_flutter_android/ # Stable Diffusion Flutter plugin
├── lucide_icons/ # Vendored Lucide icon pack (v0.257.0)
└── speech_to_text_windows/ # Windows speech-to-text plugin
android/
├── app/src/main/kotlin/com/cubiclm/app/
│ ├── MainActivity.kt # Flutter engine + channel wiring
│ ├── ModelDownloadService.kt # Foreground service: Range resume, notification
│ └── BootReceiver.kt # Boot persistence
└── res/values+drawable/launch_background.xml # Warm #F8F4ED
windows/
├── runner/ # Win32 runner (window_manager)
├── CMakeLists.txt
├── installer/cubiclm.iss # Inno Setup installer script
└── updater_config.json # auto-update scaffolding (disabled)
web/
├── index.html
└── manifest.json
scripts/
├── build-all.ps1 # One-command build (Android + Windows)
├── build-all.sh # One-command build (Android + Web + Windows)
└── sync-opencode-models.mjs # Model catalog sync
assets/
├── adblock_hosts.txt # Privacy browser host blocklist
├── catalog/models.json # Bundled model catalog
├── icons/
│ ├── CubicLM.png # App icon (splash)
│ └── CubicLM_Icon.png # App icon (launcher)
└── skills/ # 5 bundled starter skills
├── bn_en_translator.md
├── code_reviewer.md
├── creative_writer.md
├── efficient_prompting.md
└── study_helper.md
docs/
├── ARCHITECTURE.md # One product, three shells
├── PLATFORM_DIFFERENCES.md # Android full vs Web/Windows cloud-only
├── BUILD_AND_RUN.md # Clean clone → Android/Web/Windows
├── PLATFORM_LINKS.md # Single-file link editing
├── AGENT_IDE_DESIGN.md # Agent IDE design doc
├── CUBIC_WEB_SYSTEM_LOGS.md # CubicWeb diagnostics doc
├── quick_release.md # Release checklist
├── terminal.md # Terminal feature doc
├── web_builder_nextjs.md # Next.js pipeline doc
└── web_builder_react(vite).md # Vite/React pipeline doc
```
> 🧩 **File-split convention (two-dev + AI workflow):** files over ~500 lines are split into a small `main` + one `part` file per feature (`part of` + `extension … on …`), so two developers + AI agents can work without merge conflicts. Every part file carries a `Contains:` header listing its methods — check it before editing. Behavior stays identical: splits move code only, verified by `flutter analyze` (0 issues) + full test suite.
</details>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- REQUIREMENTS -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 📋 Requirements
</div>
<table>
<tr>
<td width="50%" valign="top">
### 🎯 Minimum
| Requirement | Version |
| :--- | :--- |
| 🐦 **Flutter** | `3.3.0+` |
| 🤖 **Android SDK** | minSdk 28 / Android 9+ |
| ☕ **Java** | 17 |
| 💾 **Storage** | ~500 MB (app + smallest model) |
| 🧠 **RAM** | 4 GB |
</td>
<td width="50%" valign="top">
### 🚀 Recommended
| Requirement | Version |
| :--- | :--- |
| 🐦 **Flutter** | `3.19+` (latest stable) |
| 🤖 **Android** | Android 12+ (better Vulkan) |
| 💾 **Storage** | 20+ GB (multiple models) |
| 🧠 **RAM** | 8 GB+ |
| 🎮 **GPU** | Adreno 6xx+ / Mali G7x+ |
### 🔑 For Release Builds
- Keystore configured at `android/key.properties`
- See `android/key.properties.example` for template
</td>
</tr>
</table>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- GETTING STARTED -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 🚀 Getting Started
</div>
### 1️⃣ Clone & Install
```bash
# Clone the repository
git clone https://github.com/abir2afridi/CubicLM.git
cd CubicLM
# Install dependencies
flutter pub get
# Verify Flutter setup
flutter doctor
```
### 2️⃣ Run
```bash
# Auto-picks Android/Windows/Web device from `flutter devices`
flutter run
# Android — full local inference
flutter run -d android
# Web — cloud-only (Hive IndexedDB), responsive reflow
flutter run -d chrome
# Windows — 1280×800 window_manager, cloud-only until llama.dll ported
flutter run -d windows
```
### 📦 Release Build
<table>
<tr>
<td width="50%" valign="top">
#### 🔑 Setup
1. Copy `android/key.properties.example` → `android/key.properties`
2. Fill in your keystore credentials and path:
```properties
storePassword=your_store_password
keyPassword=your_key_password
keyAlias=your_key_alias
storeFile=/path/to/your/keystore.jks
```
</td>
<td width="50%" valign="top">
#### 🏗️ Build Commands
```bash
# Android APK
flutter build apk --release
# → build/app/outputs/flutter-apk/app-release.apk
# Windows
flutter build windows
# → build/windows/runner/Release/cubiclm.exe
# (41 MB bundle; zip: 16 MB)
# Web (currently blocked by dart:ffi)
flutter build web
# → build/web
# Or one command for supported shells:
pwsh -File scripts/build-all.ps1 # Windows PowerShell
bash scripts/build-all.sh # Linux/macOS
```
</td>
</tr>
</table>
> [!NOTE]
> **Windows build prerequisites (v1.2.0):**
> - `nuget.exe` on `PATH` (`flutter_inappwebview_windows` dependency)
> - ATL headers — `Microsoft.VisualStudio.Component.VC.ATL` via Visual Studio Installer
> - Short build path if your checkout contains spaces (e.g. `C:\CLM` junction)
> - `CL=/D_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS` for MSVC 14.51
> - See [`windows/CMakeLists.txt:1,35,47`](windows/CMakeLists.txt) and [`docs/BUILD_AND_RUN.md`](docs/BUILD_AND_RUN.md)
> [!TIP]
> Set `CUBICLM_ALLOW_DEBUG_RELEASE_SIGNING=true` to skip keystore validation during development.
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- CONFIGURATION -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# ⚙️ Configuration
</div>
### 🔑 Cloud API Keys
> Tap **Add API Key** on any provider card in the **Explore** tab.
| Step | Action |
| :---: | :--- |
| 1️⃣ | 📋 Paste the key |
| 2️⃣ | ✅ Hit **Verify** — live endpoint check, nothing saved |
| 3️⃣ | 💾 **Save Key** unlocks once it shows *Verified — N models found* |
**🔀 Sorting behavior:**
- 🔝 Keyed providers sort to the top (Custom always first, then pinned, then by key-set time or A–Z)
- 🔒 Keyless ones sit in an *Add API Key* section below and **never appear in the chat model switcher**
**🔄 Refresh options:** ↻ button on a provider card, or probe every model with the activity (Test all) button.
---
### 💾 Local Models
- 📥 Download models from the **Explore** tab (with pause / resume / cancel support)
- 📁 Or import `.gguf` / `.litertlm` / `.safetensors` files via the file picker
- 🔐 Models are stored in **app-private storage**
- 🛡️ Loading is guarded — missing or corrupted files are detected before reaching the native engine, and stale download pointers are cleaned up automatically
---
### 🌐 Local API Server
> Open **Settings → Nodes** and flip the switch.
Once running, point any OpenAI-compatible client at `http://<device-ip>:8080` to use your local models programmatically.
---
### 🧩 Skills
> Manage in **Settings › Config → SKILLS** (next to Global System Prompt).
| Method | Details |
| :--- | :--- |
| ✅ **Enable / disable** | Toggle built-ins |
| 📁 **Import → From file** | `.md` via file picker |
| 🐙 **Browse Anthropic skills** | Flat list from `anthropics/skills`, cached, rate-limit safe |
| 🔗 **From URL** | Any raw markdown link, size/type checked |
> [!NOTE]
> Every import shows a preview before saving; skills are **pure text injection, never executable**. Nothing about installed skills is sent to any Abir/Anthropic server.
---
### 🔌 Custom MCP Server
> Configure in **Settings › Config → CUSTOM MCP SERVER**.
- 🌐 Single remote HTTP/SSE URL, optional bearer token (secure storage), transport auto-detected
- 🎛️ **Save / Test Connection / Enable-Disable** (with tool-preview dialog) **/ Remove** with live status (disconnected / connecting / connected / error)
- 🧠 When enabled, its tools are added to OpenAI-compatible cloud requests (`tools` / `tool_choice: auto`); tool results are round-tripped via `chat_controller` and capped
- 📴 If offline, tools are still advertised and failed calls return an error `tool_result` — **never silently omitted**
- 🏠 Local models don't use live tools (Skills still apply)
---
### ⚙️ Engine & App Configuration
<table>
<tr>
<td width="50%" valign="top">
#### 🖥️ Settings › Config
- 🔍 Diagnostics
- 🧮 Hardware capabilities
- 🎯 Inference mode
- 🪄 **Auto Tune** (context/output limits)
- 📝 Global system prompt
- 🧩 **Skills**
- 🔌 **Custom MCP Server**
#### 🎚️ Settings › Parameters
- 🎨 Local model parameters
- 🖼️ Synthetic imaging parameters
</td>
<td width="50%" valign="top">
#### 📱 App Settings
- 🎨 Theme, typography scale
- 🔮 **Thinking Orbs** (Random or fixed state per context)
- 🌍 **Language** (15 languages with instant switch)
- 🚀 Startup auto-load
- 🔒 **App Lock** re-lock timeout + biometric-only
- 💾 **Auto backup** (silent JSON every N days, last 3 kept)
- 📤 **Settings export/import** (no secrets)
- ℹ️ App info (View Update center + settings)
</td>
</tr>
</table>
### 🔐 Privacy & Chat Controls
- 🕵️ **Hidden chats** — stronger hide than archive (out of drawer AND search), per-chat menu toggle with show/hide reveal
- 🌐 **Web Access toggle** — in the chat input bar; reads links from your message into the model's context
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- SECURITY & PRIVACY -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 🔐 Security & Privacy
</div>
<table>
<tr>
<td width="50%" valign="top">
### 🛡️ What Stays On-Device
| Data | Storage |
| :--- | :--- |
| 💬 Chat history | Hive (encrypted at rest by OS) |
| 🤖 Local models | App-private storage |
| 🎨 Generated images | App-private storage |
| 📝 Skills content | Hive `skillsBox` (plain text — never uploaded) |
| 🔑 API keys | Hive (or secure storage for MCP tokens) |
| 📊 Usage estimates | Hive JSON, per-provider aggregated |
### 🔒 Secure Storage
- MCP bearer tokens use **`flutter_secure_storage`** → Android Keystore / iOS Keychain
- **Never** written to Hive or plaintext
- **Never** enters LLM context
</td>
<td width="50%" valign="top">
### 🌐 What Leaves Your Device
Only what you explicitly configure:
- ☁️ **Cloud API requests** — only to providers whose keys you've saved
- 🐙 **Skills browse** — `github.com/anthropics/skills` REST + raw fetch (cached 6h)
- 🔗 **Web Access fetches** — direct `https://…` URLs from your message
- 📊 **Firebase Crashlytics** — anonymous crash reports (can be disabled in build)
- 📥 **Model downloads** — direct from Hugging Face / release URLs
### 🚫 What CubicLM Never Does
- ❌ No telemetry beyond Crashlytics
- ❌ No analytics SDKs (no Google Analytics, no Mixpanel, no Amplitude)
- ❌ No cloud sync of chats (unless you export)
- ❌ No "phone home" pings
- ❌ No training on your data
</td>
</tr>
</table>
> [!IMPORTANT]
> **Skills are never executed.** They are **static markdown text** appended to the system prompt. No JavaScript, no shell, no FFI. A malicious skill can only try to influence the LLM's output — it cannot run code on your device.
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- FAQ -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/question/question1.gif" width="120" />
## Frequently Asked Questions
</div>
<details>
<summary><b>🤔 Is CubicLM really free?</b></summary>
<br/>
Yes — CubicLM is **MIT-licensed** and free forever. There's no premium tier, no feature gates, no ads. Cloud providers may charge you for API usage (their terms, not ours), but the app itself is 100% free and open-source.
</details>
<details>
<summary><b>📱 Will it work on my phone?</b></summary>
<br/>
Minimum is **Android 9 (API 28)** with **4 GB RAM**. For a smooth experience:
| RAM | What You Can Run |
| :--- | :--- |
| 4 GB | Qwen3-0.6B, Llama-3.2-1B |
| 6 GB | Qwen2.5-1.5B, Gemma 2 2B, Qwen2-VL-2B |
| 8 GB | Qwen2.5-3B, Llama-3.2-3B, Gemma 4 E2B |
| 12 GB+ | Gemma 4 E4B, Kimi Moonlight 16B-A3B |
</details>
<details>
<summary><b>🔋 Does local inference drain my battery?</b></summary>
<br/>
Local inference is CPU/GPU-intensive — expect **~15-25%/hour** of screen-on chat with a small model on a modern phone. Larger models (7B+) can drain faster. **Cloud providers use almost no battery** (just network I/O).
**Tips:**
- Use a smaller quantized model (Q3/Q4) for casual chat
- Enable **GPU acceleration** (Vulkan) in `Settings → Config` — faster + more efficient than CPU
- Use cloud providers for long sessions when plugged in
</details>
<details>
<summary><b>🌐 Can I use CubicLM completely offline?</b></summary>
<br/>
**Absolutely.** Once you've downloaded a model, you can chat forever without internet:
- ✅ Local inference works offline
- ✅ Chat history is local
- ✅ Skills work offline
- ✅ Web Access is optional (obviously needs internet)
- ✅ MCP requires network (it's remote)
Turn off Wi-Fi / cellular and CubicLM still functions perfectly with local models.
</details>
<details>
<summary><b>💻 Why isn't there a macOS / Linux / iOS build?</b></summary>
<br/>
The `lib/` code is **platform-agnostic** — it would run on iOS/macOS/Linux with `flutter create --platforms=<target>`. The gaps are:
- **iOS** — Apple's App Store review process for on-device LLMs is strict; also no Vulkan (Metal would need porting in `llama_flutter_android`)
- **macOS** — Same Metal issue; would need `llama_flutter_macos` plugin
- **Linux** — Would need `llama_flutter_linux` plugin; low priority given Windows covers desktop
If you want to port it: fork `local_plugins/llama_flutter_android` and adapt the FFI bindings. PRs welcome!
</details>
<details>
<summary><b>🔌 How do I use CubicLM as an API server for my homelab?</b></summary>
<br/>
1. Load a model in CubicLM
2. Go to **Settings → Nodes** and flip the server switch
3. Find your phone's IP (Settings → About → Status)
4. Point any OpenAI-compatible client at `http://<phone-ip>:8080`
**Example (Python):**
```python
from openai import OpenAI
client = OpenAI(base_url="http://192.168.1.42:8080/v1", api_key="not-needed")
resp = client.chat.completions.create(
model="local",
messages=[{"role": "user", "content": "Hello!"}]
)
print(resp.choices[0].message.content)
```
</details>
<details>
<summary><b>🧩 What's the difference between Skills and MCP?</b></summary>
<br/>
| Aspect | Skills 🧩 | MCP 🔌 |
| :--- | :--- | :--- |
| **Type** | Static prompt injection | Live tool calls |
| **Network** | None needed | Requires remote server |
| **Works on local models** | ✅ Yes | ❌ No (unreliable structured output) |
| **Works on cloud models** | ✅ Yes | ✅ Yes (OpenAI-compatible) |
| **User confirmation** | None | Ask-before-run dialog |
| **Best for** | Teaching the model *how* to respond | Giving the model *live access* to tools |
**Use Skills** for: consistent tone, coding style, translation rules, domain knowledge.
**Use MCP** for: real-time data, external APIs, database queries, file operations.
</details>
<details>
<summary><b>🔄 How do I update CubicLM?</b></summary>
<br/>
- **Android**: Download the new APK from [Releases](https://github.com/abir2afridi/CubicLM/releases). Installing over the old version preserves all data.
- **Windows**: Download the new zip, extract over the old folder. Or use the About page → View Update center (when auto-update is enabled).
Your models, chats, skills, and API keys are all preserved across updates.
</details>
<details>
<summary><b>🐛 I found a bug — where do I report it?</b></summary>
<br/>
Open an issue on [GitHub Issues](https://github.com/abir2afridi/CubicLM/issues) with:
1. **Device info** — copy from `Settings → Config → Device Specification card`
2. **Reproduction steps**
3. **System Logs** — `Settings → Config → System Logs` → Export → paste
4. **Screenshot / video** if visual
The in-app **System Logs** export includes a health dashboard that already tells us a lot — please include it.
</details>
<details>
<summary><b>💰 Can I sponsor / support development?</b></summary>
<br/>
The best support is:
- ⭐ **Star the repo** on GitHub
- 🐛 **Report bugs** with detailed info
- 📣 **Share** CubicLM with others
- 🤝 **Contribute** code or documentation
There's no donation link — this is a passion project. If you build something cool with it, let us know!
</details>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- TROUBLESHOOTING -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 🐛 Troubleshooting
</div>
| Symptom | Likely Cause | Fix |
| :--- | :--- | :--- |
| **App crashes on model load** | Model file corrupt or RAM insufficient | Check `Settings → Config → System Logs` for `ERROR [Model]`; re-download or try a smaller quant |
| **"Restart recommended" after context change** | RAM guard triggered | Lower Context Size or switch to a smaller model |
| **Streaming jank on long answers** | Large context + big model | Reduce Context Size, or use a smaller model |
| **Cloud provider returns 401** | Invalid / expired API key | Re-verify the key in Explore; some providers rotate free keys |
| **MCP tools not appearing** | Server unreachable / wrong transport | Test Connection in MCP config; check the URL scheme (http vs https) |
| **Web Access returns nothing** | Link timed out or blocked | Check System Logs for `[Web]` errors; some sites block scraping |
| **Skills not injecting** | Threshold not met | Check the skill's trigger keywords; only skills scoring >0.6 activate |
| **Windows app won't launch** | WebView2 missing | Install [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) |
| **Windows build fails with ATL error** | ATL headers not installed | Visual Studio Installer → Add `Microsoft.VisualStudio.Component.VC.ATL` |
| **`RenderFlex overflow` on small screens** | Known layout edge case | Logged as ERROR but harmless; already fixed for 360dp (see `chat_view.dart`) |
> [!TIP]
> **Before filing a bug:** export `Settings → Config → System Logs` — the health dashboard + last 500 log entries usually pinpoint the issue instantly.
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- ROADMAP -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 🗺️ Roadmap
</div>
<table>
<tr>
<td width="50%" valign="top">
### ✅ Shipped *(v1.12.0)*
- [x] Android full support (llama.cpp + LiteRT-LM)
- [x] Windows desktop (cloud-only)
- [x] 23+ cloud providers
- [x] Skills + MCP
- [x] Built-in OpenAI-compatible API server
- [x] CubicWeb Builder (Toolkit)
- [x] Thinking Orbs animation
- [x] 15 languages
- [x] Battle Arena (up to 4 models)
- [x] Per-chat model pin & lock
- [x] Web Access with visible sources
- [x] RAM guard + crash-loop guard
</td>
<td width="50%" valign="top">
### 🚧 In Progress / Planned
**Near-term**
- [ ] **Windows local inference** — `local_plugins/llama_flutter_windows` (`llama.dll`)
- [ ] **Web build unblocked** — `dart:ffi` alternative for cloud-only Web
- [x] **Windows update feed** — `windows/updater_config.json` points at GitHub Releases + zip/checksum templates; signed silent install still needs MSIX/Inno cert
- [ ] **iOS feasibility study** — Metal backend for llama.cpp
**Mid-term**
- [ ] **Voice mode** — conversational polish beyond existing STT+TTS hands-free loop
- [ ] **Multi-modal local** — more VLMs (LLaVA, Moondream)
- [x] **Free web search in chat** — Deep Search uses DuckDuckGo when no Perplexity key is set; Perplexity still preferred when keyed
- [x] **Local embeddings (v1)** — `/v1/embeddings` via on-device trigram-hash vectors (`cubiclm-trigram-hash-v1`); neural model swap planned
- [x] **Encrypted auto-backups** — optional AES-256 auto-backups with passphrase in device secure storage
- [ ] **Plugin marketplace** — community Skills + MCP registry
**Long-term**
- [ ] **Linux desktop** — `flutter create --platforms=linux`
- [ ] **macOS desktop** — Metal + `llama_flutter_macos`
- [ ] **Distributed inference** — split model across devices on LAN
</td>
</tr>
</table>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- CONTRIBUTING -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 🤝 Contributing
</div>
Contributions are welcome — code, docs, translations, bug reports, or feature ideas.
<table>
<tr>
<td width="50%" valign="top">
### 🛠️ Code Contributions
1. **Fork** the repo
2. **Branch** — `git checkout -b feature/my-feature`
3. **Follow conventions:**
- Dart: `flutter analyze` clean
- Kotlin: follow Android style
- Commit: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`)
4. **Test** on Android + Windows if possible
5. **PR** with a clear description + screenshots
</td>
<td width="50%" valign="top">
### 🌍 Translation Contributions
Adding a language is easy:
1. Open `lib/core/app_translations.dart`
2. Copy the `en` block to a new locale (e.g. `'it'`)
3. Translate the ~160 keys
4. Add to `lib/core/languages.dart`
5. Bump the `Language` count in the README
**Currently supported:** EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR
</td>
</tr>
</table>
### 📜 Code of Conduct
Be kind. Be patient. Assume good faith. This is a hobby project — maintainers contribute in their spare time.
### 🐛 Reporting Bugs
Use the [GitHub Issues](https://github.com/abir2afridi/CubicLM/issues) template. Include:
- Device info (from `Settings → Config` card)
- Steps to reproduce
- System Logs export
- Screenshots if visual
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- ACKNOWLEDGMENTS -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/love/icons8-heart-balloon.gif" />
## Acknowledgments
</div>
CubicLM stands on the shoulders of giants:
| Project | Role |
| :--- | :--- |
| 🦙 [llama.cpp](https://github.com/ggerganov/llama.cpp) | The inference engine that makes local LLMs possible on mobile |
| ⚡ [Google LiteRT-LM](https://ai.google.dev/edge) | On-device ML runtime for Android |
| 🎨 [Stable Diffusion](https://github.com/Stability-AI/stablediffusion) | Image generation backbone |
| 🐦 [Flutter](https://flutter.dev) | Cross-platform UI framework |
| 🧩 [dart_mcp](https://pub.dev/packages/dart_mcp) | MCP client for Dart |
| 🎯 [GetX](https://pub.dev/packages/get) | State management |
| 🗄️ [Hive](https://pub.dev/packages/hive) | Fast local storage |
| 🔥 [Firebase](https://firebase.google.com) | Crash reporting |
| 🎨 [Lucide Icons](https://lucide.dev) | Icon set |
| 🤗 [Hugging Face](https://huggingface.co) | Model hosting |
And to the **open-source community** that made every one of these tools free and accessible.
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- LICENSE -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
# 📄 License
**MIT License**
Copyright © Abir Afridi
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. See [LICENSE](LICENSE) for full text.
</div>
---
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!-- FOOTER -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->
<div align="center">
<br/>
### ⭐ If CubicLM made your day, consider starring the repo!
It helps others discover the project and keeps development going.
<br/>
<a href="https://github.com/abir2afridi/CubicLM/stargazers">
<img src="https://img.shields.io/github/stars/abir2afridi/CubicLM?style=for-the-badge&color=facc15&labelColor=0d1117&logo=github" alt="Stars"/>
</a>
<a href="https://github.com/abir2afridi/CubicLM/network/members">
<img src="https://img.shields.io/github/forks/abir2afridi/CubicLM?style=for-the-badge&color=3b82f6&labelColor=0d1117&logo=github" alt="Forks"/>
</a>
<a href="https://github.com/abir2afridi/CubicLM/issues">
<img src="https://img.shields.io/github/issues/abir2afridi/CubicLM?style=for-the-badge&color=ef4444&labelColor=0d1117&logo=github" alt="Issues"/>
</a>
<a href="https://github.com/abir2afridi/CubicLM/releases">
<img src="https://img.shields.io/github/downloads/abir2afridi/CubicLM/total?style=for-the-badge&color=22c55e&labelColor=0d1117&logo=github" alt="Downloads"/>
</a>
<br/><br/>
<p>
<sub>Built with ❤️ by <a href="https://github.com/abir2afridi"><b>Abir Afridi</b></a> and contributors</sub><br/>
<sub><i>CubicLM — Your AI, your device, your rules.</i></sub>
</p>
<br/>
<img src="assets/icons/CubicLM.png" alt="CubicLM" width="48" />
<br/>
<!-- Star History Chart -->
<a href="https://star-history.com/#abir2afridi/CubicLM&Date">
<img src="https://api.star-history.com/svg?repos=abir2afridi/CubicLM&type=Date" alt="Star History" width="600"/>
</a>
<br/><br/>
<sub><b>✨ Every feature, capability & detail from the original README is preserved — upgraded into an advanced, magazine-style layout ✨</b></sub>
<sub><b>✨ No information was removed — this is a full design upgrade with extensive new sections added ✨</b></sub>
</div>
<!-- ═══════════════════════════════════════════════════════════════════ -->
<!-- ░░ FOOTER BAR ░░ -->
<!-- ═══════════════════════════════════════════════════════════════════ -->
<div align="center">
<br/>
<table>
<tr>
<td align="center">
<sub>
💡 <b>Pro tip:</b> Press <kbd>Ctrl</kbd> + <kbd>F</kbd> to search · <kbd>T</kbd> for the file tree · <kbd>Esc</kbd> to close dialogs
</sub>
<br/><br/>
<a href="#cubiclm">
<img src="https://img.shields.io/badge/⬆_Back_to_Top-FF4D00?style=for-the-badge&logo=rocket&logoColor=white&labelColor=0d1117" alt="Top"/>
</a>
</td>
</tr>
</table>
<br/>
</div>
Connection Info
You Might Also Like
No recommendations available